diff --git a/antora.yml b/antora.yml index 6113323..7831e9e 100644 --- a/antora.yml +++ b/antora.yml @@ -3,7 +3,7 @@ title: Red Hat Open Training Developer Guide version: 1 nav: - modules/ROOT/nav.adoc -- modules/starthere/nav.adoc -- modules/quickcourse/nav.adoc +- modules/start_here/nav.adoc +- modules/course_guide/nav.adoc - modules/lab/nav.adoc - modules/references/nav.adoc diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index ec2db36..443c109 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -3,8 +3,15 @@ == Introduction -This comprehensive guide serves as a reference for anyone looking to contribute to the training content development via Red Hat Open Training creation program. +This comprehensive guide serves as a reference for anyone interested in developing or contributing training content via the Red Hat Open Training program. -The Open Training Creation program empowers subject matter experts within the organization to share their knowledge and expertise across the company and beyond. +The Open Training program empowers subject matter experts within the organization to share their knowledge and expertise across the company and beyond. +Read more about the program https://spaces.redhat.com/pages/viewpage.action?pageId=512755273[here,window=_blank]. -This offering aims to reduce the time required to build training content while addressing challenges such as covering a wide range of technologies, adapting to fast-changing product life cycles, and meeting the diverse needs of different audiences. \ No newline at end of file +A key goal of this program is to enable "citizen developers" and reduce the time required to build and maintain training content. +Creating training content for such a wide variety of products and technologies with fast product lifecycles to meet the needs of different audiences is impossible to do alone. +It takes more than a single team to do this and Red Hat is the perfect place to solicit content and participation from a large group of highly skilled people that care about each other's success. + +If you are here, you are already interested. +Move on to the xref:start_here:workflow.adoc[Getting Started] section if you are new to this. +Otherwise, use the menu on the left to find a section you need. \ No newline at end of file diff --git a/modules/quickcourse/.DS_Store b/modules/course_guide/.DS_Store similarity index 100% rename from modules/quickcourse/.DS_Store rename to modules/course_guide/.DS_Store diff --git a/modules/quickcourse/images/click-devspace-button.png b/modules/course_guide/images/click-devspace-button.png similarity index 100% rename from modules/quickcourse/images/click-devspace-button.png rename to modules/course_guide/images/click-devspace-button.png diff --git a/modules/quickcourse/images/click-login-with-openshift.png b/modules/course_guide/images/click-login-with-openshift.png similarity index 100% rename from modules/quickcourse/images/click-login-with-openshift.png rename to modules/course_guide/images/click-login-with-openshift.png diff --git a/modules/quickcourse/images/devspace-pop-up.png b/modules/course_guide/images/devspace-pop-up.png similarity index 100% rename from modules/quickcourse/images/devspace-pop-up.png rename to modules/course_guide/images/devspace-pop-up.png diff --git a/modules/quickcourse/images/devspace-runtask.png b/modules/course_guide/images/devspace-runtask.png similarity index 100% rename from modules/quickcourse/images/devspace-runtask.png rename to modules/course_guide/images/devspace-runtask.png diff --git a/modules/quickcourse/images/ocp-devspace-login.png b/modules/course_guide/images/ocp-devspace-login.png similarity index 100% rename from modules/quickcourse/images/ocp-devspace-login.png rename to modules/course_guide/images/ocp-devspace-login.png diff --git a/modules/quickcourse/images/qc-structure.jpg b/modules/course_guide/images/qc-structure.jpg similarity index 100% rename from modules/quickcourse/images/qc-structure.jpg rename to modules/course_guide/images/qc-structure.jpg diff --git a/modules/quickcourse/images/select-workspace-1.png b/modules/course_guide/images/select-workspace-1.png similarity index 100% rename from modules/quickcourse/images/select-workspace-1.png rename to modules/course_guide/images/select-workspace-1.png diff --git a/modules/quickcourse/images/select-workspace-2.png b/modules/course_guide/images/select-workspace-2.png similarity index 100% rename from modules/quickcourse/images/select-workspace-2.png rename to modules/course_guide/images/select-workspace-2.png diff --git a/modules/quickcourse/images/trust-authors.png b/modules/course_guide/images/trust-authors.png similarity index 100% rename from modules/quickcourse/images/trust-authors.png rename to modules/course_guide/images/trust-authors.png diff --git a/modules/course_guide/nav.adoc b/modules/course_guide/nav.adoc new file mode 100644 index 0000000..6d57b0e --- /dev/null +++ b/modules/course_guide/nav.adoc @@ -0,0 +1,4 @@ +* xref:index.adoc[] +** xref:course_structure.adoc[] +** xref:dev_spaces.adoc[] +** xref:local_system.adoc[] \ No newline at end of file diff --git a/modules/quickcourse/pages/section3.adoc b/modules/course_guide/pages/course_structure.adoc similarity index 87% rename from modules/quickcourse/pages/section3.adoc rename to modules/course_guide/pages/course_structure.adoc index eea589c..0ebae1b 100644 --- a/modules/quickcourse/pages/section3.adoc +++ b/modules/course_guide/pages/course_structure.adoc @@ -1,10 +1,10 @@ -= Quick course content format guide += Course Structure image::../qc-structure.jpg[] The structure of the course is organized as a hierarchy, so it's helpful to think of the content in terms of chapters, or modules, and then pages, or sections. -At the top level (course), the antora.yml file defines the overall structure. It has the course title and the links to `nav.adoc` files in each module (aka chapter - they are the same thing here). +At the top level (course), the antora.yml file defines the overall structure. It has the course title and the links to `nav.adoc` files in each module (aka chapter - they are the same thing here). [source] ---- diff --git a/modules/quickcourse/pages/section1.adoc b/modules/course_guide/pages/dev_spaces.adoc similarity index 60% rename from modules/quickcourse/pages/section1.adoc rename to modules/course_guide/pages/dev_spaces.adoc index 5589cda..cc302ac 100644 --- a/modules/quickcourse/pages/section1.adoc +++ b/modules/course_guide/pages/dev_spaces.adoc @@ -1,37 +1,43 @@ = Use Devspace (skip if using local system) -:toc: -== Get started +Every Open Training course is developed in public GitHub repositories. +In order to make development as easy as possible, we provide you with the option of using a Dev Spaces instance. +If you're not familiar with this, just think of it as your normal IDE (VSCode in this case) running in the cloud. +It has everything you should need to write asciidoc, render into a preview, and interact with GitHub to push and pull. -Follow the instructions on xref:starthere:workflow.adoc[Get Started] page and wait for a response from the training team. +:toc: -== Draft content +== Set up or Access Dev Spaces Instance -. Once you receive your GitHub content repository, go to your GitHub project page and, in the README section, click the `Developer Workspace` button. +. After the GitHub repository is created for the course, you will see a `Developer Workspace` button in the README section of the repository. ++ +Click this button to launch the Dev Spaces instance. + image::../click-devspace-button.png[] + +. When prompted, select the `Log in with OpenShift` button and use the credentials that you were provided. + -. On the next page, click the `Log in with OpenShift` button. +This is usually your Red Hat SSO credential. + image::../click-login-with-openshift.png[] -+ -. Use the credentials provided by the training team to log in. -+ -image::../ocp-devspace-login.png[] -+ -. Click on the option to `Open the existing workspace` or `Switch to running workspace` if prompted. + +. Once you have successfully logged in, select the option to `Open the existing workspace` or `Switch to running workspace` if prompted. + Ignore this step if not prompted for this option. + image::../select-workspace-1.png[] + -or -+ image::../select-workspace-2.png[] -+ + . When the VSCode interface loads, click `Yes, I trust the authors`. + image::../trust-authors.png[] ++ +NOTE: Why do I trust them? + +That is it! +You are ready to start writing your content. +The file and folder structure is already in place, so you just need to start filling in blanks and deleting files that you won't need. == Render content draft diff --git a/modules/course_guide/pages/index.adoc b/modules/course_guide/pages/index.adoc new file mode 100644 index 0000000..f74e4ad --- /dev/null +++ b/modules/course_guide/pages/index.adoc @@ -0,0 +1,16 @@ += Course Contributor Guide + +This section contains instructions on how to write your content. + +First, you can find the overall course structure guide xref:course_structure.adoc[here]. +If you are familiar with Antora, you have a small head start. +If you are new to this, don't worry - you only need to know a few things before you start working on your content. + +After this, you can choose your approach to developing the content. +We have provided two options for you: + +. Use a xref:dev_spaces.adoc[Dev Spaces] instance configured to work with the course repository. +If you're not used to using an IDE and are not as familiar with git, this is a good option for you. + +. Use your xref:local_system.adoc[local system]. +If you want to use your own customized IDE and you know how to use git, this option is for you. diff --git a/modules/quickcourse/pages/section2.adoc b/modules/course_guide/pages/local_system.adoc similarity index 100% rename from modules/quickcourse/pages/section2.adoc rename to modules/course_guide/pages/local_system.adoc diff --git a/modules/quickcourse/nav.adoc b/modules/quickcourse/nav.adoc deleted file mode 100644 index 8dcc0c4..0000000 --- a/modules/quickcourse/nav.adoc +++ /dev/null @@ -1,4 +0,0 @@ -* xref:index.adoc[] -** xref:section1.adoc[] -** xref:section2.adoc[] -** xref:section3.adoc[] \ No newline at end of file diff --git a/modules/quickcourse/pages/index.adoc b/modules/quickcourse/pages/index.adoc deleted file mode 100644 index e97eb9e..0000000 --- a/modules/quickcourse/pages/index.adoc +++ /dev/null @@ -1,4 +0,0 @@ -= QuickCourse Contributor Guide - -This section contains instructions on how to use Red Hat Quick Course to build your content. -You may either use xref:section1.adoc[use devspace] or xref:section2.adoc[your local system] to develop the content. \ No newline at end of file diff --git a/modules/references/pages/asciidocqrg.adoc b/modules/references/pages/asciidocqrg.adoc index 7709030..4badd5f 100644 --- a/modules/references/pages/asciidocqrg.adoc +++ b/modules/references/pages/asciidocqrg.adoc @@ -66,20 +66,20 @@ Link to an *external website* with the https://docs.asciidoctor.org/asciidoc/lat Link to an external website with https://docs.asciidoctor.org/asciidoc/latest/[click here,window=_blank]. ---- -Link to a different *page in the same section* with xref:text.adoc[the other page within the same section]. (This will open in the same browser window.) +Link to a different *page in the same section* with xref:faq.adoc[the other page within the same section]. (This will open in the same browser window.) .Syntax: [source] ---- -Link to another page in the same section with xref:text.adoc[the other page within the same section]. +Link to another page in the same section with xref:faq.adoc[the other page within the same section]. ---- -Link to a *page in a different section* with xref:demolab:section1.adoc[the other page in the different section]. (This will open in the same browser window.) +Link to a *page in a different section* with xref:course_guide:course_structure.adoc[the other page in the different section]. (This will open in the same browser window.) .Syntax: [source] ---- -Link to a page in a different section with xref:demolab:section1.adoc[the other page in the different section]. +Link to a page in a different section with xref:course_guide:course_structure.adoc[the other page in the different section]. ---- == LISTS AND BULLETS diff --git a/modules/starthere/nav.adoc b/modules/start_here/nav.adoc similarity index 100% rename from modules/starthere/nav.adoc rename to modules/start_here/nav.adoc diff --git a/modules/start_here/pages/workflow.adoc b/modules/start_here/pages/workflow.adoc new file mode 100644 index 0000000..5372e11 --- /dev/null +++ b/modules/start_here/pages/workflow.adoc @@ -0,0 +1,30 @@ += Getting started + +You don't need to overplan, but you should have a plan. +Follow these high level steps to get started: + +. Make sure you know what kind of training you want to create. +There are a few different types to choose from: +* xref:references:glossary.adoc#Know-It[know-it training] focuses on knowledge content and does not have any lab environments. +Think about this as something closer to a blog. +* xref:references:glossary.adoc#How-To[how-to training] focuses on hands-on labs across a variety of activities from installation to use-cases with Red Hat products. +* xref:references:glossary.adoc#Break-Fix[break-fix training] is a subset of how-to and focuses on on troubleshooting activities in a hands-on lab environment. + +. If you need a learner to have a lab environment, decide which one you want to use: +* xref:references:glossary.adoc#RHDP[Red Hat Demo Platform (RHDP)] is the preferred lab type and should be suitable for all *how-to* and *break-fix* content. +* xref:references:glossary.adoc#ROLE[ROLE] can be used for content that has an established plan for publication on the GLS platform. + +. Submit a https://docs.google.com/forms/d/e/1FAIpQLSepUaRiRdyA3PEzLP8w59reAsKRe19dL3ewpJGvJ7Gbggt-xg/viewform[training request,window=_blank] for type *Open Training*. +This will notify our Learning Product Managers and they will contact you as quickly as possible either with a request for more information or with the next steps, which is usually to connect you with the team that will help get your work going. ++ +NOTE: You may track or update your request in https://issues.redhat.com/secure/RapidBoard.jspa?rapidView=20243[Jira,window=_blank]. + +. Once the request is validated and approved, write the content and work with the PTL team to develop the lab environment. +This is the part that you came here to do and where you should spend most of your time. + +== What Next? + +Once you have completed these steps and are ready to start, you can find more guidance in the following sections: + +* xref:course_guide:index.adoc[Course development] +* xref:lab:index.adoc[Lab development] \ No newline at end of file diff --git a/modules/starthere/pages/workflow.adoc b/modules/starthere/pages/workflow.adoc deleted file mode 100644 index 74eed7a..0000000 --- a/modules/starthere/pages/workflow.adoc +++ /dev/null @@ -1,16 +0,0 @@ -= Get started - -. Identify training type: xref:references:glossary.adoc#Know-It[know-it], xref:references:glossary.adoc#How-To[how-to], xref:references:glossary.adoc#Break-Fix[break-fix] -. Identify lab template on the xref:references:glossary.adoc#RHDP[RHDP] or xref:references:glossary.adoc#ROLE[ROLE] platform for how-to and break-fix type content. -. Submit a https://docs.google.com/forms/d/e/1FAIpQLSepUaRiRdyA3PEzLP8w59reAsKRe19dL3ewpJGvJ7Gbggt-xg/viewform[Request form,window=_blank] for type *Open Training* -. Training team will get in touch with you. - -**What will be the next steps?** - -* Develop xref:quickcourse:index.adoc[training] and xref:lab:index.adoc[lab] -* Quality check and Publish - - -NOTE: You may track or update your request https://issues.redhat.com/secure/RapidBoard.jspa?rapidView=20243[here,window=_blank] - -