Codestin Search App

diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.yml deleted file mode 100644 index 067a464..0000000 --- a/.github/workflows/deploy-site.yml +++ /dev/null @@ -1,53 +0,0 @@ -name: Build and deploy website - -on: - # Runs on pushes targeting the default branch - push: - branches: [$default-branch] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - build: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - steps: - - name: Checkout Repository - uses: actions/checkout@v3 - - name: Extract assets - run: docker cp $(docker run --detach quay.io/redhat-docs/redhat-docs-template):/assets ./modular-docs-manual/assets - - name: Build AsciiDoc - uses: docker://quay.io/redhat-docs/redhat-docs-template - with: - args: modular-docs-manual/master.adoc - - name: Copy output to docs/ - run: | - mkdir docs - cp -r modular-docs-manual/assets/ docs/assets - cp -r modular-docs-manual/files/ docs/files - cp -r modular-docs-manual/images/ docs/images - mv index.html docs/ - - name: Setup Pages - uses: actions/configure-pages@v3 - - name: Upload artifact - uses: actions/upload-pages-artifact@v1 - with: - path: './docs' - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v2 diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/CODEOWNERS b/CODEOWNERS deleted file mode 100644 index edb9ae3..0000000 --- a/CODEOWNERS +++ /dev/null @@ -1,6 +0,0 @@ -# Set the FCC Review Board team to own the entire repo -# (so that we can request (and require) PR reviews before merging). -* @redhat-documentation/fcc-review-board - -# Additional (more granular) ownership rules: - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index abf7401..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,114 +0,0 @@ -# Contributor's guide for the Modular Documentation Project - -## Getting started - -### Request project access - -To join the Modular Documentation Project, email `ccs-mod-docs@redhat.com` with "REQUESTING ACCESS" in the subject and your GitHub username in the body. - -### Set up your workspace - -#### Fork the repository - -1. **Fork** the [Modular Docs Repository](https://github.com/redhat-documentation/modular-docs) on GitHub. For more information, see GitHub's [Forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) topic. - -#### Clone your fork - -2. **Clone** your fork to your local machine: - - ```bash - git clone git@github.com:/modular-docs.git - ``` - - For more information, see GitHub's [Cloning your forked repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository) topic. - -#### Configure an upstream remote - -3. **Configure an upstream remote** to sync with the original repository: - - ```bash - cd modular-docs - git remote add upstream git@github.com:redhat-documentation/modular-docs.git - ``` - - For more information, see GitHub's [Configuring git to sync your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository) topic. - -#### Verify the remotes - -4. **Verify the remotes** and check your project's status: - - ```bash - git remote -v - git status - ``` - - The output should look like this: - - ``` - origin https://github.com//modular-docs.git (fetch) - origin https://github.com//modular-docs.git (push) - upstream https://github.com/redhat-documentation/modular-docs.git (fetch) - upstream https://github.com/redhat-documentation/modular-docs.git (push) - On branch main - Your branch is up to date with 'origin/main'. - - nothing to commit, working tree clean - ``` - -## Making contributions - -### Stay updated - -* **Prepare your main branch**: - - ```bash - git checkout main - git fetch upstream main - git rebase upstream/main - git switch -c - ``` - - Example: - - ```bash - git switch -c create_master_adoc - ``` - -### Make your changes - -1. **Edit content** or add new material as needed. - -2. **Stage, commit, and push** your updates: - - ```bash - git add - git commit -m "" - git push origin HEAD - ``` - - Example: - - ```bash - git add modular-doc-manual/master.adoc - git commit -m "Updated the master.adoc file" - git push origin HEAD - ``` - -4. **Create a pull request** by opening the link in the command output. - - Example: - - ```bash - remote: Create a pull request for '' on GitHub by visiting: - remote: https://github.com/rolfedh/modular-docs/pull/new/ - ``` - -### Requesting a team review for your PR - - 1. **Initiate a review** by adding `fcc-review-board` under *Reviewers* in the PR and posting a request in [#ccs-mod-docs-steering-committee](https://redhat.enterprise.slack.com/archives/C04QRCA35K8) (private) or [#forum-ccs-mod-docs](https://redhat.enterprise.slack.com/archives/C04RPJLJJ9E) (public) on Slack. - - 2. **Engage with feedback** and resolve any issues or suggestions raised by reviewers. - - 3. **Follow up**, if needed, by gently reminding reviewers or reposting to the Slack channel after you make significant changes. - - 4. **Close the issue**: After your PR gains the necessary approvals and a review board member has merged it, close the issue associated with your PR. diff --git a/LICENSE.txt b/LICENSE.txt deleted file mode 100644 index 3b7b82d..0000000 --- a/LICENSE.txt +++ /dev/null @@ -1,427 +0,0 @@ -Attribution-ShareAlike 4.0 International - -======================================================================= - -Creative Commons Corporation ("Creative Commons") is not a law firm and -does not provide legal services or legal advice. Distribution of -Creative Commons public licenses does not create a lawyer-client or -other relationship. Creative Commons makes its licenses and related -information available on an "as-is" basis. Creative Commons gives no -warranties regarding its licenses, any material licensed under their -terms and conditions, or any related information. Creative Commons -disclaims all liability for damages resulting from their use to the -fullest extent possible. - -Using Creative Commons Public Licenses - -Creative Commons public licenses provide a standard set of terms and -conditions that creators and other rights holders may use to share -original works of authorship and other material subject to copyright -and certain other rights specified in the public license below. The -following considerations are for informational purposes only, are not -exhaustive, and do not form part of our licenses. - - Considerations for licensors: Our public licenses are - intended for use by those authorized to give the public - permission to use material in ways otherwise restricted by - copyright and certain other rights. Our licenses are - irrevocable. Licensors should read and understand the terms - and conditions of the license they choose before applying it. - Licensors should also secure all rights necessary before - applying our licenses so that the public can reuse the - material as expected. Licensors should clearly mark any - material not subject to the license. This includes other CC- - licensed material, or material used under an exception or - limitation to copyright. More considerations for licensors: - wiki.creativecommons.org/Considerations_for_licensors - - Considerations for the public: By using one of our public - licenses, a licensor grants the public permission to use the - licensed material under specified terms and conditions. If - the licensor's permission is not necessary for any reason--for - example, because of any applicable exception or limitation to - copyright--then that use is not regulated by the license. Our - licenses grant only permissions under copyright and certain - other rights that a licensor has authority to grant. Use of - the licensed material may still be restricted for other - reasons, including because others have copyright or other - rights in the material. A licensor may make special requests, - such as asking that all changes be marked or described. - Although not required by our licenses, you are encouraged to - respect those requests where reasonable. More_considerations - for the public: - wiki.creativecommons.org/Considerations_for_licensees - -======================================================================= - -Creative Commons Attribution-ShareAlike 4.0 International Public -License - -By exercising the Licensed Rights (defined below), You accept and agree -to be bound by the terms and conditions of this Creative Commons -Attribution-ShareAlike 4.0 International Public License ("Public -License"). To the extent this Public License may be interpreted as a -contract, You are granted the Licensed Rights in consideration of Your -acceptance of these terms and conditions, and the Licensor grants You -such rights in consideration of benefits the Licensor receives from -making the Licensed Material available under these terms and -conditions. - - -Section 1 -- Definitions. - - a. Adapted Material means material subject to Copyright and Similar - Rights that is derived from or based upon the Licensed Material - and in which the Licensed Material is translated, altered, - arranged, transformed, or otherwise modified in a manner requiring - permission under the Copyright and Similar Rights held by the - Licensor. For purposes of this Public License, where the Licensed - Material is a musical work, performance, or sound recording, - Adapted Material is always produced where the Licensed Material is - synched in timed relation with a moving image. - - b. Adapter's License means the license You apply to Your Copyright - and Similar Rights in Your contributions to Adapted Material in - accordance with the terms and conditions of this Public License. - - c. BY-SA Compatible License means a license listed at - creativecommons.org/compatiblelicenses, approved by Creative - Commons as essentially the equivalent of this Public License. - - d. Copyright and Similar Rights means copyright and/or similar rights - closely related to copyright including, without limitation, - performance, broadcast, sound recording, and Sui Generis Database - Rights, without regard to how the rights are labeled or - categorized. For purposes of this Public License, the rights - specified in Section 2(b)(1)-(2) are not Copyright and Similar - Rights. - - e. Effective Technological Measures means those measures that, in the - absence of proper authority, may not be circumvented under laws - fulfilling obligations under Article 11 of the WIPO Copyright - Treaty adopted on December 20, 1996, and/or similar international - agreements. - - f. Exceptions and Limitations means fair use, fair dealing, and/or - any other exception or limitation to Copyright and Similar Rights - that applies to Your use of the Licensed Material. - - g. License Elements means the license attributes listed in the name - of a Creative Commons Public License. The License Elements of this - Public License are Attribution and ShareAlike. - - h. Licensed Material means the artistic or literary work, database, - or other material to which the Licensor applied this Public - License. - - i. Licensed Rights means the rights granted to You subject to the - terms and conditions of this Public License, which are limited to - all Copyright and Similar Rights that apply to Your use of the - Licensed Material and that the Licensor has authority to license. - - j. Licensor means the individual(s) or entity(ies) granting rights - under this Public License. - - k. Share means to provide material to the public by any means or - process that requires permission under the Licensed Rights, such - as reproduction, public display, public performance, distribution, - dissemination, communication, or importation, and to make material - available to the public including in ways that members of the - public may access the material from a place and at a time - individually chosen by them. - - l. Sui Generis Database Rights means rights other than copyright - resulting from Directive 96/9/EC of the European Parliament and of - the Council of 11 March 1996 on the legal protection of databases, - as amended and/or succeeded, as well as other essentially - equivalent rights anywhere in the world. - - m. You means the individual or entity exercising the Licensed Rights - under this Public License. Your has a corresponding meaning. - - -Section 2 -- Scope. - - a. License grant. - - 1. Subject to the terms and conditions of this Public License, - the Licensor hereby grants You a worldwide, royalty-free, - non-sublicensable, non-exclusive, irrevocable license to - exercise the Licensed Rights in the Licensed Material to: - - a. reproduce and Share the Licensed Material, in whole or - in part; and - - b. produce, reproduce, and Share Adapted Material. - - 2. Exceptions and Limitations. For the avoidance of doubt, where - Exceptions and Limitations apply to Your use, this Public - License does not apply, and You do not need to comply with - its terms and conditions. - - 3. Term. The term of this Public License is specified in Section - 6(a). - - 4. Media and formats; technical modifications allowed. The - Licensor authorizes You to exercise the Licensed Rights in - all media and formats whether now known or hereafter created, - and to make technical modifications necessary to do so. The - Licensor waives and/or agrees not to assert any right or - authority to forbid You from making technical modifications - necessary to exercise the Licensed Rights, including - technical modifications necessary to circumvent Effective - Technological Measures. For purposes of this Public License, - simply making modifications authorized by this Section 2(a) - (4) never produces Adapted Material. - - 5. Downstream recipients. - - a. Offer from the Licensor -- Licensed Material. Every - recipient of the Licensed Material automatically - receives an offer from the Licensor to exercise the - Licensed Rights under the terms and conditions of this - Public License. - - b. Additional offer from the Licensor -- Adapted Material. - Every recipient of Adapted Material from You - automatically receives an offer from the Licensor to - exercise the Licensed Rights in the Adapted Material - under the conditions of the Adapter's License You apply. - - c. No downstream restrictions. You may not offer or impose - any additional or different terms or conditions on, or - apply any Effective Technological Measures to, the - Licensed Material if doing so restricts exercise of the - Licensed Rights by any recipient of the Licensed - Material. - - 6. No endorsement. Nothing in this Public License constitutes or - may be construed as permission to assert or imply that You - are, or that Your use of the Licensed Material is, connected - with, or sponsored, endorsed, or granted official status by, - the Licensor or others designated to receive attribution as - provided in Section 3(a)(1)(A)(i). - - b. Other rights. - - 1. Moral rights, such as the right of integrity, are not - licensed under this Public License, nor are publicity, - privacy, and/or other similar personality rights; however, to - the extent possible, the Licensor waives and/or agrees not to - assert any such rights held by the Licensor to the limited - extent necessary to allow You to exercise the Licensed - Rights, but not otherwise. - - 2. Patent and trademark rights are not licensed under this - Public License. - - 3. To the extent possible, the Licensor waives any right to - collect royalties from You for the exercise of the Licensed - Rights, whether directly or through a collecting society - under any voluntary or waivable statutory or compulsory - licensing scheme. In all other cases the Licensor expressly - reserves any right to collect such royalties. - - -Section 3 -- License Conditions. - -Your exercise of the Licensed Rights is expressly made subject to the -following conditions. - - a. Attribution. - - 1. If You Share the Licensed Material (including in modified - form), You must: - - a. retain the following if it is supplied by the Licensor - with the Licensed Material: - - i. identification of the creator(s) of the Licensed - Material and any others designated to receive - attribution, in any reasonable manner requested by - the Licensor (including by pseudonym if - designated); - - ii. a copyright notice; - - iii. a notice that refers to this Public License; - - iv. a notice that refers to the disclaimer of - warranties; - - v. a URI or hyperlink to the Licensed Material to the - extent reasonably practicable; - - b. indicate if You modified the Licensed Material and - retain an indication of any previous modifications; and - - c. indicate the Licensed Material is licensed under this - Public License, and include the text of, or the URI or - hyperlink to, this Public License. - - 2. You may satisfy the conditions in Section 3(a)(1) in any - reasonable manner based on the medium, means, and context in - which You Share the Licensed Material. For example, it may be - reasonable to satisfy the conditions by providing a URI or - hyperlink to a resource that includes the required - information. - - 3. If requested by the Licensor, You must remove any of the - information required by Section 3(a)(1)(A) to the extent - reasonably practicable. - - b. ShareAlike. - - In addition to the conditions in Section 3(a), if You Share - Adapted Material You produce, the following conditions also apply. - - 1. The Adapter's License You apply must be a Creative Commons - license with the same License Elements, this version or - later, or a BY-SA Compatible License. - - 2. You must include the text of, or the URI or hyperlink to, the - Adapter's License You apply. You may satisfy this condition - in any reasonable manner based on the medium, means, and - context in which You Share Adapted Material. - - 3. You may not offer or impose any additional or different terms - or conditions on, or apply any Effective Technological - Measures to, Adapted Material that restrict exercise of the - rights granted under the Adapter's License You apply. - - -Section 4 -- Sui Generis Database Rights. - -Where the Licensed Rights include Sui Generis Database Rights that -apply to Your use of the Licensed Material: - - a. for the avoidance of doubt, Section 2(a)(1) grants You the right - to extract, reuse, reproduce, and Share all or a substantial - portion of the contents of the database; - - b. if You include all or a substantial portion of the database - contents in a database in which You have Sui Generis Database - Rights, then the database in which You have Sui Generis Database - Rights (but not its individual contents) is Adapted Material, - - including for purposes of Section 3(b); and - c. You must comply with the conditions in Section 3(a) if You Share - all or a substantial portion of the contents of the database. - -For the avoidance of doubt, this Section 4 supplements and does not -replace Your obligations under this Public License where the Licensed -Rights include other Copyright and Similar Rights. - - -Section 5 -- Disclaimer of Warranties and Limitation of Liability. - - a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE - EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS - AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF - ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, - IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, - WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR - PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, - ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT - KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT - ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. - - b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE - TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, - NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, - INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, - COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR - USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR - DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR - IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. - - c. The disclaimer of warranties and limitation of liability provided - above shall be interpreted in a manner that, to the extent - possible, most closely approximates an absolute disclaimer and - waiver of all liability. - - -Section 6 -- Term and Termination. - - a. This Public License applies for the term of the Copyright and - Similar Rights licensed here. However, if You fail to comply with - this Public License, then Your rights under this Public License - terminate automatically. - - b. Where Your right to use the Licensed Material has terminated under - Section 6(a), it reinstates: - - 1. automatically as of the date the violation is cured, provided - it is cured within 30 days of Your discovery of the - violation; or - - 2. upon express reinstatement by the Licensor. - - For the avoidance of doubt, this Section 6(b) does not affect any - right the Licensor may have to seek remedies for Your violations - of this Public License. - - c. For the avoidance of doubt, the Licensor may also offer the - Licensed Material under separate terms or conditions or stop - distributing the Licensed Material at any time; however, doing so - will not terminate this Public License. - - d. Sections 1, 5, 6, 7, and 8 survive termination of this Public - License. - - -Section 7 -- Other Terms and Conditions. - - a. The Licensor shall not be bound by any additional or different - terms or conditions communicated by You unless expressly agreed. - - b. Any arrangements, understandings, or agreements regarding the - Licensed Material not stated herein are separate from and - independent of the terms and conditions of this Public License. - - -Section 8 -- Interpretation. - - a. For the avoidance of doubt, this Public License does not, and - shall not be interpreted to, reduce, limit, restrict, or impose - conditions on any use of the Licensed Material that could lawfully - be made without permission under this Public License. - - b. To the extent possible, if any provision of this Public License is - deemed unenforceable, it shall be automatically reformed to the - minimum extent necessary to make it enforceable. If the provision - cannot be reformed, it shall be severed from this Public License - without affecting the enforceability of the remaining terms and - conditions. - - c. No term or condition of this Public License will be waived and no - failure to comply consented to unless expressly agreed to by the - Licensor. - - d. Nothing in this Public License constitutes or may be interpreted - as a limitation upon, or waiver of, any privileges and immunities - that apply to the Licensor or You, including from the legal - processes of any jurisdiction or authority. - - -======================================================================= - -Creative Commons is not a party to its public -licenses. Notwithstanding, Creative Commons may elect to apply one of -its public licenses to material it publishes and in those instances -will be considered the “Licensor.” The text of the Creative Commons -public licenses is dedicated to the public domain under the CC0 Public -Domain Dedication. Except for the limited purpose of indicating that -material is shared under a Creative Commons public license or as -otherwise permitted by the Creative Commons policies published at -creativecommons.org/policies, Creative Commons does not authorize the -use of the trademark "Creative Commons" or any other trademark or logo -of Creative Commons without its prior written consent including, -without limitation, in connection with any unauthorized modifications -to any of its public licenses or any other arrangements, -understandings, or agreements concerning use of licensed material. For -the avoidance of doubt, this paragraph does not form part of the -public licenses. - -Creative Commons may be contacted at creativecommons.org. diff --git a/README.md b/README.md deleted file mode 100644 index 013704a..0000000 --- a/README.md +++ /dev/null @@ -1,74 +0,0 @@ -# The Modular Documentation Project Source Repository - -## Modular Documentation Reference Guide ![Build Status](https://github.com/redhat-documentation/modular-docs/actions/workflows/deploy-site.yml/badge.svg) - -The Modular Documentation Reference Guide contains the essential information to start writing documentation in a modular way. -You can view the latest build of the guide here: - -https://redhat-documentation.github.io/modular-docs/ - -## Modular Documentation Template Files - -Another deliverable for this project is the module templates for the various module types. -All the module template files for writing new modular content can be found here: - -https://github.com/redhat-documentation/modular-docs/tree/master/modular-docs-manual/files - -## What is the Purpose of the Modular Documentation Project? - -To provide documentation teams with a set of resources to assist them as they write user-driven content or convert their current documentation framework to a modular-based documentation framework. - -## Why Are We Doing This? - -To help the documentation teams become more agile with their documentation. This agility will help us to better serve our readers with a more purposeful reading experience. A modular-based content model sets a foundation for innovation. Modular documentation provides a structure for writing and presenting user-story-based documentation. User-story-based documentation attempts to address the reader's needs more than focusing on feature-based documentation. User-story-based documentation also helps the documentation teams with the amount of documents that they have to maintain, by helping them to focus on what really matters. - -## Any Suggestions or Questions? - -Please submit an [issue](https://github.com/redhat-documentation/modular-docs/issues) to this project. - -## Repository Structure - -This repository uses the following directory structure: - -``` -. -├── .travis.yml (YAML configuration file for Travis CI) -├── CONTRIBUTING.md (How do I contribute to this project?) -├── README.md (this file) -├── modular-docs-manual/ (Another book) - ├── README.md (the README file) - ├── master.adoc (master layout of the book) - ├── content/ - ├── topics/ - └── *.adoc (AsciiDoc files) - └── modular-doc-manual.adoc - ├── files/ (template files) - ├── images (image files) - └── common-content - └── attributes.adoc (common attributes) -``` - -## Contributing - -We welcome contributions from everyone who feels they have something of value that all of the community can benefit from. Follow these instructions to start contributing: [CONTRIBUTING](CONTRIBUTING.md). - -## License - -This work is licensed under the [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/). - -## Building the Books Locally - -When you make changes to these books, it is a good practice to do a local test build to verify the book builds successfully and renders as you expect before you submit the merge request back to upstream master. - -### Configuring the Build Environment - -You can build the book locally using [AsciiDoctor](http://asciidoctor.org/docs/#get-started-with-asciidoctor). - -### Building the Modular Documentation Reference Guide - -To build and view the document locally, run: - -``` -$ asciidoctor modular-docs-manual/master.adoc -$ modular-docs-manual/master.html -``` diff --git a/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc b/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc similarity index 61% rename from modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc rename to files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc index 6a8a763..4e260bb 100644 --- a/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc +++ b/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc @@ -6,31 +6,39 @@ See also the complementary step on the last line of this file. ifdef::context[:parent-context: {context}] - -//// -Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type. -//// -:_mod-docs-content-type: ASSEMBLY - //// Base the file name and the ID on the assembly title. For example: * file name: assembly-my-user-story.adoc * ID: [id="assembly-my-user-story_{context}"] * Title: = My user story +//// -ID is a unique identifier that can be used to reference this assembly. Avoid changing it after the module has been published to ensure existing links are not broken. Include {context} in the ID so the assembly can be reused. +//// +Indicate the content type in one of the following +ways: +Add the prefix assembly- or assembly_ to the file name. +Add the following attribute before the module ID: +:_content-type: ASSEMBLY +//// -Be sure to include a line break between the title and the :context: variable and the :context: variable and the assembly introduction. -If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring. //// +The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken. Include {context} in the ID so the assembly can be reused. +//// + [id="assembly-my-user-story_{context}"] = My user story //// -The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide. +Be sure to include a line break between the title and the :context: variable and the :context: variable and the assembly introduction. + +If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring. //// :context: assembly-keyword +//// +The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide. +//// + [role="_abstract"] This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. @@ -44,36 +52,30 @@ This paragraph is the assembly introduction. It explains what the user will acco //// The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies. - -[leveloffset=+1] ensures that when a module title is a level 1 heading (= Title), the heading will be interpreted as a level-2 heading (== Title) in the assembly. Use [leveloffset=+2] and [leveloffset=+3] to nest modules in an assembly. - - Add a blank line after each 'include::' statement. //// -include::TEMPLATE_CONCEPT_concept-explanation.adoc[leveloffset=+1] - -include::TEMPLATE_PROCEDURE_doing-one-procedure.adoc[leveloffset=+2] +include::modules/TEMPLATE_CONCEPT_explaining_a_concept.adoc[leveloffset=+1] -include::TEMPLATE_REFERENCE_reference-material.adoc[leveloffset=+2] - -== Next steps +//// +[leveloffset=+1] ensures that when a module title is a level 1 heading (= Title), the heading will be interpreted as a level-2 heading (== Title) in the assembly. Use [leveloffset=+2] and [leveloffset=+3] to nest modules in an assembly. +//// -* This section is optional. -* Provide information about the next steps the user might want to take. -* This section can include text and links. +include::modules/TEMPLATE_PROCEDURE_doing_one_procedure.adoc[leveloffset=+2] +// Add a blank line after each 'include::' statement. -// If the last module included in your assembly contains an Additional resources section as well, check the appearance of the rendered assembly. If the two Additional resources sections might be confusing for a reader, consider consolidating their content and removing one of them. +include::modules/TEMPLATE_PROCEDURE_reference-material.adoc[leveloffset=2] [role="_additional-resources"] -== Additional resources +== Additional resources (or Next steps) //// Optional. Delete if not used. -Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text. //// -* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] - -// Restore the context to what it was before this assembly. +* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros. +* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +//// +Restore the context to what it was before this assembly. +//// ifdef::parent-context[:context: {parent-context}] ifndef::parent-context[:!context:] diff --git a/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc b/files/TEMPLATE_CONCEPT_concept-explanation.adoc similarity index 57% rename from modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc rename to files/TEMPLATE_CONCEPT_concept-explanation.adoc index ea22c0a..62deb2e 100644 --- a/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc +++ b/files/TEMPLATE_CONCEPT_concept-explanation.adoc @@ -1,26 +1,33 @@ -//// -Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type. -//// - -:_mod-docs-content-type: CONCEPT - //// Base the file name and the ID on the module title. For example: * file name: con_my-concept-module-a.adoc * ID: [id="my-concept-module-a_{context}"] * Title: = My concept module A +//// - ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken. - -The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide. +//// +Indicate the module type in one of the following +ways: +Add the prefix con- or con_ to the file name. +Add the following attribute before the module ID: +:_content-type: CONCEPT +//// -Be sure to include a line break between the title and the module introduction. +//// +The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken. //// [id="my-concept-module-a_{context}"] + +//// +The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide. +//// + = My concept module A //// -In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly. Do not start the title of concept modules with a verb or gerund. See also _Wording of headings_ in _IBM Style_. +In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly. Do not start the title of concept modules with a verb. See also _Wording of headings_ in _The IBM Style Guide_. + +Be sure to include a line break between the title and the module introduction. //// [role="_abstract"] @@ -34,19 +41,20 @@ The contents of a concept module give the user descriptions and explanations nee //// -Do not include third-level headings (===). -Include titles and alternative text descriptions for images and enclose the descriptions in straight quotation marks (""). Alternative text should provide a textual, complete description of the image as a full sentence. +Include titles and alternative text descriptions for images. +Alternative text should provide a textual, complete description of the image as a full sentence. Images should never be the sole means of conveying information and should only supplement the text. -Avoid screenshots or other images that might quickly go out of date and that create a maintenance burden on documentation. Provide text equivalents for every diagram, image, or other non-text element. Avoid using images of text instead of actual text. +Avoid screenshots or other images that might quickly go out of date and that create a maintenance burden on documentation. +Provide text equivalents for every diagram, image, or other non-text element. Avoid using images of text instead of actual text. //// //.Image title -//image::image-file.png["A textual representation of the essential information conveyed by the image."] +//image::image-file.png[A textual representation of the essential information conveyed by the image.] [role="_additional-resources"] .Additional resources //// Optional. Delete if not used. -Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text. //// -* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] +* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros. +* For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. diff --git a/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc b/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc new file mode 100644 index 0000000..8eef464 --- /dev/null +++ b/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc @@ -0,0 +1,69 @@ +//// +Base the file name and the ID on the module title. For example: +* file name: proc_doing-procedure-a.adoc +* ID: [id="doing-procedure-a_{context}"] +* Title: = Doing procedure A + +Indicate the module type in one of the following +ways: +Add the prefix proc- or proc_ to the file name. +Add the following attribute before the module ID: +:_content-type: PROCEDURE + +The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken. The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in an assembly file. +//// + +[id="doing-procedure-a_{context}"] + += Doing procedure A +//// +Start the title of a procedure module with a gerund, such as Creating, Installing, or Deploying. +//// + +[role="_abstract"] +Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization. + +.Prerequisites + +* A bulleted list of conditions that must be satisfied before the user starts the steps in this module. +* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. + +//// +If you have only one prerequisite, list it as a single bullet point. +Do not write prerequisites in the imperative. +You can include links to more information about the prerequisites. +Delete the .Prerequisites section title and bullets if the module has no prerequisites. +//// + +.Procedure + +. Make each step an instruction. + +. Include one command or action for each step with the exception of simple follow-step, for example: +.. Do this thing and then select *Next*. +.. Do this other thing and then select *Next*. + +. Use an unnumbered bullet (*) if the procedure includes only one step. + +.Verification +//// +Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. +//// +. Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful. + +. List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure. + +. Make each step an instruction. + +. Include one command or action per step. + +. Use an unnumbered bullet (*) if the verification includes only one step. + +[role="_additional-resources"] +.Additional resources +//// +Optional. Delete if not used. +//// +* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros. +* For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. diff --git a/modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc b/files/TEMPLATE_REFERENCE_reference-material.adoc similarity index 59% rename from modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc rename to files/TEMPLATE_REFERENCE_reference-material.adoc index b1f6885..5043144 100644 --- a/modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc +++ b/files/TEMPLATE_REFERENCE_reference-material.adoc @@ -1,39 +1,46 @@ -//// -Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type. -//// -:_mod-docs-content-type: REFERENCE - //// Base the file name and the ID on the module title. For example: * file name: ref_my-reference-a.adoc * ID: [id="my-reference-a_{context}"] * Title: = My reference A +//// - ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken. - -The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide. +//// +Indicate the module type in one of the following +ways: +Add the prefix ref- or ref_ to the file name. +Add the following attribute before the module ID: +:_content-type: REFERENCE +//// -Be sure to include a line break between the title and the module introduction. +//// +The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken. //// [id="reference-material_{context}"] + +//// +The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide. +//// + = Reference material //// In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly. -on. + +Be sure to include a line break between the title and the module introduction. //// [role="_abstract"] Write a short introductory paragraph that provides an overview of the module. -A reference module provides data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want. - +A reference module provides data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table. +A well-organized reference module enables users to scan it quickly to find the details they want. AsciiDoc markup to consider for reference data: .Unordered list * For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. * Use a consistent system for file names, IDs, and titles. -For tips, see _File names and anchors_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. .Labeled list Term 1:: Definition @@ -51,7 +58,7 @@ Term 2:: Definition .Additional resources //// Optional. Delete if not used. -Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text. //// -* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] +* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros. +* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. diff --git a/modular-docs-manual/images/concept-diagram.dia b/images/concept-diagram.dia similarity index 100% rename from modular-docs-manual/images/concept-diagram.dia rename to images/concept-diagram.dia diff --git a/modular-docs-manual/images/concept-diagram.png b/images/concept-diagram.png similarity index 100% rename from modular-docs-manual/images/concept-diagram.png rename to images/concept-diagram.png diff --git a/modular-docs-manual/images/modules_assemblies.dia b/images/modules_assemblies.dia similarity index 100% rename from modular-docs-manual/images/modules_assemblies.dia rename to images/modules_assemblies.dia diff --git a/modular-docs-manual/images/modules_assemblies.png b/images/modules_assemblies.png similarity index 100% rename from modular-docs-manual/images/modules_assemblies.png rename to images/modules_assemblies.png diff --git a/modular-docs-manual/images/nested-assemblies-correct.odt b/images/nested-assemblies-correct.odt similarity index 100% rename from modular-docs-manual/images/nested-assemblies-correct.odt rename to images/nested-assemblies-correct.odt diff --git a/modular-docs-manual/images/nested-assemblies-correct.png b/images/nested-assemblies-correct.png similarity index 100% rename from modular-docs-manual/images/nested-assemblies-correct.png rename to images/nested-assemblies-correct.png diff --git a/modular-docs-manual/images/nested-assemblies-error.odt b/images/nested-assemblies-error.odt similarity index 100% rename from modular-docs-manual/images/nested-assemblies-error.odt rename to images/nested-assemblies-error.odt diff --git a/modular-docs-manual/images/nested-assemblies-error.png b/images/nested-assemblies-error.png similarity index 100% rename from modular-docs-manual/images/nested-assemblies-error.png rename to images/nested-assemblies-error.png diff --git a/modular-docs-manual/images/procedure-diagram.dia b/images/procedure-diagram.dia similarity index 100% rename from modular-docs-manual/images/procedure-diagram.dia rename to images/procedure-diagram.dia diff --git a/modular-docs-manual/images/procedure-diagram.png b/images/procedure-diagram.png similarity index 100% rename from modular-docs-manual/images/procedure-diagram.png rename to images/procedure-diagram.png diff --git a/index.html b/index.html new file mode 100644 index 0000000..184dca5 --- /dev/null +++ b/index.html @@ -0,0 +1,2038 @@ + + + + + + + + +Codestin Search App + + + + + + +

1. Introduction to modular documentation

This manual provides instructions on how to author modularly structured documentation based on user stories. The manual defines used terminology, describes components that form modular documentation, and instructs writers on how to use provided templates to turn user stories into modular documentation.

+ + + + + +

+ +	+As modular documentation imperatives continue to evolve, the details and recommendations in this guide might be modified. +

2. Understanding modular documentation

This chapter explains what modular documentation is and what it is not.

2.1. What modular documentation is

Modular documentation is documentation based on modules, which the writer combines into assemblies. An assembly can also include other assemblies. A module should not contain another module.

+ + + + + +

+ +	+ + Nesting assemblies too deep can create too much complexity, which might make the documentation difficult to use and maintain. If you are worried this might be the case, consider linking to another assembly as an alternative to direct inclusion. + +

At Red Hat, we write modular documentation that is based on user stories. This means that each assembly documents a user story.

Figure 1. Schema of a module and an assembly

Additional resources

+
For definitions of the terms we use, including modules, assemblies, and user stories, see Modular documentation terms and definitions.
+

2.2. What modular documentation is not

Legacy (non-modular) documentation split into small, meaningless pieces

A module must make sense and provide value on its own, even when read separately from the other modules. The templates included in this manual help ensure this.

A collection of modules that have no relationship to one another

An unorganized set of modules is confusing to users. That is why we combine modules into:

+
Assemblies that are based on user stories
+
+
Deliverables, like a book or help system, that present a structured view of the body of knowledge represented by a set of modules
+

Always a linear, book-type model

Modular documentation is designed to enable you to deliver content flexibly. You can combine modules to build lean, article-based content or large, linear books.

2.3. Modular documentation repositories

Due to many factors that determine repository design for individual products, these modular documentation guidelines do not provide a strict documentation repository template.

For a general repository structure used by documentation teams at Red Hat, see the example documentation repository and README file in the mod-doc-repo-example branch in this repository.

3. Writing modular documentation

Assemblies can include various types of modules. Use the instructions in the following sections to create modules and combine them into assemblies.

3.1. Creating modules

Follow these guidelines to create different types of modules:

A module should not contain another module. However a module can contain a text snippet. For information about text snippets, see Using Text Snippets.

See Module and assembly examples for real-world examples of assemblies, modules, and their individual parts.

3.1.1. Creating concept modules

This section explains what a concept module is and provides recommended practices for writing concept modules.

Concept module definition

A concept module is an "understand" module. Concept modules give the user descriptions and explanations needed to understand and use a product.

Concept module guidelines

The core requirement for a concept module is explaining the idea, or concept. +A concept module requires a short introduction and optionally, can also include additional resources.

When planning a concept module, look at nouns in related procedure modules and assemblies to find the concepts to explain to users. +Explain only things that are visible to users. +Even if a concept is interesting, it probably does not require an explanation if it is not visible to users.

Concept introduction

The introduction to a concept module is a single, concise paragraph that provides a short overview of the module. +A short description makes the module more usable because users can quickly determine whether the concept is useful without having to read the entire module.

The introduction typically answers the following questions:

+
What is the concept?
+
+
Why should the user care about the concept?
+

Concept body

The concept body describes the subject of the concept module.

Apart from paragraphs, you can use other AsciiDoc elements, such as lists, tables, or examples. +Consider including graphics or diagrams to speed up the understanding of the concept.

Avoid including instructions to perform an action. Action items belong in procedure modules. However, in some cases a concept or reference module can include suggested actions when those actions are simple, are highly dependent on the context of the module, and have no place in any procedure module. In such cases, ensure that the heading of the concept or reference remains a noun phrase and not a gerund. For example, see +"Bound variables in patterns and constraints" and the sections that follow it. These concept and reference modules contain actions that are not suitable for standalone procedure modules but are relevant actions to understand in the context of the concept or reference being described.

See also The DITA Topic Types at _informationmapping.com for more information about different types of conceptual information: principle, concept, structure, process, and fact.

If the concept module is large and complex, consider splitting the concept module into multiple standalone concept modules. If you cannot split the module into meaningful standalone modules, consider using subheadings in the module to structure the content for improved reader navigation. If you use subheadings in a concept module, you can add the [discrete] tag to exclude each subheading from the table of contents, if needed. However, in many cases, subheadings are helpful to include in the table of contents to improve content searchability.

The following examples illustrate a discrete and a standard subheading:

Example discrete subheading excluded from table of contents

= My concept module
+
+Concept introduction and body
+
+[discrete]
+== My concept module subheading
+
+More concept body content

Example subheading included in table of contents

= My concept module
+
+Concept introduction and body
+
+== My concept module subheading
+
+More concept body content

+ + + + + +

+ +	+You can use subheadings in concept or reference modules, but not in procedure modules. +

Concept additional resources

The optional additional resources list links to other material closely related to the contents of the concept module, for example, other documentation resources.

Focus on relevant resources that might interest the user. Do not list resources for completeness.

Additional resources

+
Download the concept module template (adoc file) for new projects.
+
+
For real-world examples of concept modules, see Concept module examples.
+

3.1.2. Procedure modules

Procedure modules explain how to do something. A procedure module contains numbered, step-by-step instructions to help the user accomplish a single task. Sometimes those tasks include substeps. Procedure modules must include a title, a brief introduction, and one or more steps in the form of imperative statements. Procedure modules can also contain prerequisites, verification steps, and additional resources or next steps.

Figure 2. Schema of a procedure module

Procedure title

The title of a procedure module is a gerund phrase, such as Deploying OpenShift Container Platform.

Procedure introduction

The procedure introduction is a short paragraph that provides an overview of the module. The introduction includes what the module will help the user do and why it will be beneficial to the user. It includes key words that relate to the module to maximize search engine optimization.

The introduction typically provides context for the procedure, such as:

+
Why and where the user performs the procedure
+
+
Special considerations specific to the procedure
+

Procedure prerequisites

This section is optional. Prerequisites are a bulleted list of conditions that must be satisfied before the user starts the procedure. Use a bulleted list for prerequisites and the plural heading Prerequisites, even if you only have a single prerequisite.

Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel.

Focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites. If a prerequisite applies to all of the procedures in a user story, consider listing the prerequisite in the assembly file. If you do this, consider including the prerequisite in the procedure module as a comment.

Procedure steps

The procedure consists of one or more steps required to complete the procedure. Each step describes one action. For single-step procedures, use an unnumbered bullet instead of a numbered list.

+ + + + + +

+ +	+Not all numbered lists in documentation are procedures. You can also use numbered lists in any module type for non-procedural sequences, such as a process flow of system actions. +

Procedure verification

This section is optional. It provides the user with one or more steps to verify that the procedure provided the intended outcome, for example:

+
An example of expected command output or a pop-up window that the user receives when the procedure is successful
+
+
Actions for the user to complete, such as entering a command, to determine the success or failure of the procedure
+

Procedure additional resources

This section is optional. The additional resources list links to other material closely related to the contents of the procedure module, such as other documentation resources, instructional videos, or labs.

Focus on relevant resources that might interest the user. Do not list resources for completeness. If a resource applies to all of the modules in a user story, consider listing the resource in the Additional resources section of the assembly file. If you do this, consider including the resource in the procedure module as a comment.

Additional resources

+
Download the procedure module template (adoc file) for new projects.
+
+
For real-world examples of procedure modules, see Procedure module examples.
+

3.1.3. Creating reference modules

This section explains what a reference module is and provides recommended practices for writing reference modules.

Reference module definition

Reference modules provide data that users might want to look up, but do not need to remember.

Example 1. Common documentation examples of reference modules

+
A list of commands that users can use with an application
+
+
A table of configuration files with definitions and usage examples
+
+
A list of default settings for a product
+

Example 2. Reference modules explained using a real-life example

For documentation on how to cross the road, you could create these modules:

+
Concept modules:
+
+
- +
  What are roads
  +
- +
  What are crossings
  +
+
+
+
Procedure modules:
+
+
- +
  How to put one foot in front of another
  +
- +
  How to use pedestrian traffic lights
  +
- +
  How to see if the road is clear for crossing
  +
+
+
+
Reference modules:
+
+
- +
  Crossing signals
  +
- +
  Common crosswalk pavement markings
  +
- +
  Crossing laws by country
  +
+
+

Reference module guidelines

The required part of a reference module is the reference data. +A reference module requires a short introduction.

Reference introduction

The introduction to a reference module is a single, concise paragraph that provides a short overview of the module. A short description makes the module more usable because users can quickly determine whether the reference is useful without having to read the entire module.

Reference body

A reference module has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want.

To make the reference data easier to scan, organize it in a logical order (such as alphabetically) or as a table. AsciiDoc markup to consider for reference data:

+
Lists (unordered, labeled)
+
+
Tables
+

If you have a large volume of the same type of information to document, use a structure into which the information details can fit, and then document each logical unit of information as one reference module. For example, think of man pages, which document very different information details, but which still use consistent titles and formats to present those details in a uniform information structure.

If the reference module is large and complex, consider splitting the reference module into multiple standalone reference modules. If you cannot split the module into meaningful standalone modules, consider using subheadings in the module to structure the content for improved reader navigation. If you use subheadings in a reference module, you can add the [discrete] tag to exclude each subheading from the table of contents, if needed. However, in many cases, subheadings are helpful to include in the table of contents to improve content searchability.

The following examples illustrate a discrete and a standard subheading:

Example discrete subheading excluded from table of contents

= My reference module
+
+Reference introduction and body
+
+[discrete]
+== My reference module subheading
+
+More reference body content

Example subheading included in table of contents

= My reference module
+
+Reference introduction and body
+
+== My reference module subheading
+
+More reference body content

+ + + + + +

+ +	+You can use subheadings in concept or reference modules, but not in procedure modules. +

Additional resources

+
Download the reference module template (adoc file) for new projects.
+
+
For real-world examples of reference modules, see Reference module examples.
+
+
For advice on when to use lists and when to use tables, see Let’s bring <table> to the table, again.
+

3.1.4. Text snippets

A text snippet is a section of text that is stored in an AsciiDoc file. Text snippets contain content that is reused in multiple modules or assemblies.

+ + + + + +

+ +	+A text snippet is not a module. It cannot include structural elements of a module such as an anchor ID or an H1 heading. +

Examples of snippets:

+
One or more paragraphs of text
+
+
A step or series of steps in a procedure
+
+
A table or list
+

A note, for example a disclaimer for technology preview or beta releases

+ + ++++ + + + + + + + + + + + + + + + + + + + + +

Table 1. Types of notes
Note type	Suggested content
NOTE	Additional guidance or advice that improves product configuration, performance, or supportability.
IMPORTANT	Advisory information essential to the completion of a task. Users must not disregard this information.
WARNING	Information about potential system damage, data loss, or a support-related issue if the user disregards this admonition. Explain the problem, cause, and offer a solution that works. If available, offer information to avoid the problem in the future or state where to find more information.

Procedure

+
Create the text snippet AsciiDoc file.
+
+ + + + + +
+ + +Consider storing snippet files in a separate snippets folder. +
+
+
+
Indicate that the file is a snippet in one of the following ways:
+
+
- +
  Prefix the file name with snip- or snip_:
  +
  +
  +
  snip-beta-note.adoc
  +
  +
  +
- +
  Add a variable to the snippet file that identifies its content type:
  +
  +
  +
  :_content-type: SNIPPET
  +
  +
  +
+
+
+
Add an include:: statement to the file that you want to add the snippet to, for example:
+
+
+
```
include::snippets/snip-beta-note.adoc[]
```
+
+
+

3.1.5. File names and anchors

To optimize modular documentation, follow these guidelines for naming files and creating anchors:

File names

Create assembly and module file names that accurately and closely reflect the title of the assembly or module. Create file names with the format prefix-filename.adoc or prefix_filename.adoc where prefix is one of the following module prefixes:

+
con: Concept module prefix
+
+
proc: Procedure module prefix
+
+
ref: Reference module prefix
+
+
assembly: Assembly module prefix
+

Examples

+
con-guided-decision-tables.adoc (Concept module)
+
+
con_guided-decision-tables.adoc (Concept module)
+
+
proc-creating-guided-decision-tables.adoc (Procedure module for creating)
+
+
proc_creating-guided-decision-tables.adoc (Procedure module for creating)
+
+
ref-guided-decision-table-examples.adoc (Reference module with examples)
+
+
ref_guided-decision-table-examples.adoc (Reference module with examples)
+
+
assembly-designing-guided-decision-tables.adoc (Assembly of guided decision table modules)
+
+
assembly_designing-guided-decision-tables.adoc (Assembly of guided decision table modules)
+

+ + + + + +

+ +	+ + Do not include special characters in file names. Ensure that all members of your team use the same file naming conventions. + +

These file naming guidelines are optional but highly recommended. However, if your team does not include the module prefixes in file names followed by either a hyphen (-) or an underscore (_), include one of the following variables in each file before the anchor ID:

:_content-type: ASSEMBLY
+:_content-type: PROCEDURE
+:_content-type: CONCEPT
+:_content-type: REFERENCE
+:_content-type: SNIPPET

Anchors

At the top of every module, provide an anchor in the format [id="filename_{context}"] where filename is the exact name of the file, without the file extension (.adoc) and a module prefix. Module anchors are necessary so that Asciidoctor can identify the module when the module is reused or cross-referenced. The context variable is defined in each assembly module, such as :context: my-context-value. When you build an assembly, the value of the context variable replaces context in each module anchor ID and is displayed in the generated URL.

[id="filename_{context}"]
+= Module Heading
+
+The first sentence of the topic.

Example 1. Concept module

[id="guided-decision-tables_{context}"]
+= Guided Decision Tables
+
+The guided decision tables feature works similarly to ...

Example 2. Procedure module

[id="creating-guided-decision-tables_{context}"]
+= Creating Guided Decision Tables
+
+You can use guided decision tables to ...

+ + + + + +

+ +

Note on other anchor formats (not recommended)

The anchor format defined here is recommended because it is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced correctly. For details, see Reusing modules in assemblies. Other anchor formats include [[anchor-name]] and [#anchor-name], but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time.

Additional resources

+
Asciidoctor User Manual
+

3.2. Forming assemblies

This section explains what an assembly is and provides recommended practices for forming assemblies.

3.2.1. Assembly definition

An assembly is a collection of modules that describes how to accomplish a user story. See also Understanding modular documentation.

3.2.2. Assembly guidelines

The required parts of an assembly are the introduction and modules. Optionally, an assembly can also include prerequisites and additional resources.

Assembly title

If the assembly describes a task and includes one or more procedure modules, start the title with a verb in the gerund form, such as Creating or Configuring, for example Encrypting block devices using LUKS. If the assembly does not include any procedure modules, use a noun phrase, for example Red Hat Process Automation Manager API reference.

Assembly introduction

The introduction explains what the user accomplishes by working through the assembled modules. It typically provides context for the assembly.

Consider rewording the user story to write the assembly introduction, for example:

+
User story: As an administrator, I want to provide external identity, authentication and authorization services for my Atomic Host, so that users from external identity sources can access the Atomic Host.
+
+
Assembly introduction: As a system administrator, you can use SSSD in a container to provide external identity, authentication, and authorization services for the Atomic Host system. This enables users from external identity sources to authenticate to the Atomic Host.
+

Assembly prerequisites

Prerequisites are conditions that must be satisfied before the user can start following the assembly and are applicable to all the modules in the assembly.

Use the second level heading syntax for the Prerequisites section in the assembly so that it is displayed in the table of contents and is consistent with the Additional resources or Next steps sections in the assembly.

Assembly modules

To include modules in an assembly, use the Asciidoc include directive. Use any combination of concept, procedure, and reference modules that fulfills the purpose of the assembly. Use the leveloffset attribute to set the hierarchy of the module relative to the assembly, as shown in the following example:

Level offset for module files

file1.adoc[leveloffset=+1]
+file2.adoc[leveloffset=+2]
+file3.adoc[leveloffset=+3]

All module and assembly titles must use the H1 heading designation, such as = My heading.

Assembly additional resources

The optional additional resources list links to other material closely related to the contents of the assembly, for example, other documentation resources, instructional videos, or labs.

Focus on relevant resources that might interest the user. Do not list resources for completeness.

3.2.3. Additional resources

+
Download the assembly template (adoc file) for new projects.
+
+
For real-world examples of assemblies, see Assembly examples.
+

3.2.4. Reusing modules in assemblies

When you create content in modules, you can use the same module multiple times in an assembly without having to replicate information in multiple source files. However, in order to facilitate module reuse, you must embed a document attribute variable in the anchor name for the module and then define that variable in the assembly each time the reused module appears. If the variable is not embedded and assigned, an error appears at build time reporting the duplicated anchor ID.

+ + + + + +

+ +	+ + To determine which assemblies include a specific file, you can use your code editor to search the doc repo for instances of the file name. The search results will list every `include:` statement that specifies the file. + +

Example 3. Error at build time when anchor has no variable

ID "$ANCHOR_NAME" is duplicated in the source content
+$BUILD_PATH fails to validate

This error is resolved by adding and defining a document variable.

Procedure

In the module file that will be reused, add the {context} suffix with a hyphen to the anchor name in the format [id="anchor-name_writing-mod-docs"].

+ + + + + +

+ + +Although you can use any document variable that clearly indicates the variable in question, such as {product} or {chapter}, the {context} variable is recommended. This variable indicates more generally that the same module can be reused in the specified "context" of one section of a document or another, regardless of whether that section is product-specific or not, whether it is a whole chapter or a small assembly, or some other limitation. +

Two modules to be reused: Module A and Module B

[id="module-A-being-reused_{context}"]
+= Module A Heading

[id="module-B-being-reused_{context}"]
+= Module B Heading

+
In the assembly file or the master book file, define the :context: variable immediately above any included modules that are being reused, in the format :context: variable-name. How you define the variable depends on whether the module is included once in multiple assemblies or is included multiple times in a single assembly. Note that the :context: variable definition uses hyphens to separate its terms.
+
+
+
Module included once in multiple assemblies
+
+
If the reused modules are included only once in this assembly and in at least one other assembly, define an assembly-level variable such as :context: assembly-name. This indicates that the reused module is appearing in the context of that assembly.
+
+
Assembly 1
+
+
include::some-module-not-being-reused.adoc + +:context: assembly-1-name +include::module-A-being-reused.adoc + +include::some-module-not-being-reused.adoc + +:context: assembly-1-name +include::module-B-being-reused.adoc
+
+
+
+
Assembly 2
+
+
include::some-module-not-being-reused.adoc + +:context: assembly-2-name +include::module-A-being-reused.adoc + +include::some-module-not-being-reused.adoc + +:context: assembly-2-name +include::module-B-being-reused.adoc
+
+
+
+
Module included multiple times in a single assembly
+
+
If a module is included multiple times in the same assembly, define a variable specific to a section or a chapter of that assembly, such as :context: section-name. This indicates that the reused module is appearing in the context of that section of the assembly.
+
+
Assembly
+
+
include::some-module-not-being-reused.adoc + +:context: section-1-name +include::module-A-being-reused.adoc + +include::some-module-not-being-reused.adoc + +:context: section-2-name +include::module-A-being-reused.adoc
+
+
+
+
+
+
+
Return to the reused module file, and at the top of the file add a comment that identifies which assemblies the module has been added to. This helps to track reused modules in the future.
+
+
+
```
[id="module-A-being-reused_{context}"]
+= Module A Heading
```
+
+
+

Additional resources

+
The Asciidoctor User Manual.
+

Practical example 1: reusing modules in multiple assemblies

You want to reuse the "Creating Assets" procedure module and the "Projects" concept module in two assemblies: an "Asset Definitions" assembly and a "Business Rules" assembly.

The module files contain the following content:

projects.adoc

[id="projects_{context}"]
+= Projects

creating-assets.adoc

[id="creating-assets_{context}"]
+= Creating Assets

The assembly files contain the following content:

asset-definitions.adoc

include::organizational-unit.adoc
+
+include::repository.adoc
+
+:context: asset-definitions
+include::projects.adoc
+
+include::organizational-unit.adoc
+
+include::creating-packages.adoc
+
+:context: asset-definitions
+include::creating-assets.adoc
+
+include::adding-dependencies.adoc

business-rules.adoc

include::business-processes.adoc
+
+:context: business-rules
+include::projects.adoc
+
+include::project-types.adoc
+
+include::packages.adoc
+
+:context: business-rules
+include::creating-assets.adoc

For all cross-references to the reused modules, specify which context (assembly) you want to link to. For example, you can link to the "Creating Assets" procedure module as it appears either in the "Asset Definitions" assembly or in the "Business Rules" assembly. Create cross-references in the xref:anchor-name_context-variable-name[] format:

For details, see xref:creating-assets_asset-definitions[].

For details, see xref:creating-assets_business-rules[].

Practical example 2: reusing a module in a single assembly

You want to reuse the "Projects" concept module twice in the "Business Rules" assembly.

The module file contains the following content:

projects.adoc

[id="projects_{context}"]
+= Projects

The assembly file contains the following content:

business-rules.adoc

:context: intro
+include::projects.adoc
+
+include::organizational-unit.adoc
+
+include::asset-types.adoc
+
+:context: asset-types
+include::projects.adoc
+
+include::dependencies.adoc

For all cross-references to the reused module, specify which context (section) you want to link to. For example, you can link to the "Projects" module as it appears either in the "Introduction" or in the "Asset Types" section. You create cross-references in the format xref:anchor-name_context-variable-name[]:

For details, see xref:projects_introduction[].

For details, see xref:projects_asset-types[].

3.2.5. Nesting assemblies in assemblies

When you set the :context: variable in an assembly, the variable continues to be set to the same value in the rest of the document even after the assembly itself ends. This causes problems if you include an assembly in another assembly.

If there is, for example, an Additional Resources section in the inner, included assembly as well as in the outer, including assembly after the include statements, the ID of the second one gets overwritten with the :context: variable of the included assembly. This causes duplicate IDs, which lead to build-time errors like:

asciidoctor: WARNING: 1.adoc: line 19: id assigned to section already in use: additional-resources-2

Example 4. Nested assemblies with a duplicate ID

To solve this problem, restore the :context: variable to its previous value when assemblies end:

+
Add the following line at the top of your assemblies before :context: is defined to save the inherited context:
+
+
+
```
ifdef::context[:parent-context: {context}]
```
+
+
+
+
Add the following lines to the end of your assemblies to restore the saved context, if one already existed:
+
+
+
```
ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
```
+
+
+

Example 5. Correctly nested assemblies

See also the assembly template for an example.

Appendix A: Modular documentation terms and definitions

Assembly

A collection of several modules combined into a larger piece of text, preceded by an introduction that explains the purpose of the assembly.

The docs realization of a user story.

Module

An independent, self-contained chunk of information with a well-organized structure. Each module is information that a reader can understand and use by itself. A writer can use a module as a standalone article or as part of a larger body of work (an "Assembly"). A module does not depend on other documents, but it can refer the reader to other documents as additional resources. Because a module is self-contained, it must have a clear title that briefly and clearly summarizes the subject of the module. Moreover, because modules are written as context-free elements independent of other modules, they are re-usable. One module can be part of multiple assemblies.

Concept module: +
Explains a concept; for example, not action-based.
+
Procedure module: +
Describes steps to perform an action.
+
Reference Module: +
Presents detailed reference material, for example, command syntax.
+

User story

A short description of something the user does to achieve a goal.

Example: As an administrator, I want to set up authentication to a critical system in my infrastructure, such as a gateway VPN, or accounting system to only allow users authenticated through strong authentication methods, such as two-factor authentication.

As opposed to a use case, which is a description of interactions between the system and the user or other systems.

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Table 2. Contrasting user stories and use cases

User Story

Use Cases

Definitions:

A short description of something the user does to achieve a goal.

A description of interactions between the system and the user, components of the system, or the system and other systems.

Views the situation from:

The perspective of a user.

The perspective of a product and its features.

Focuses on:

The outcome as perceived by the user.

What the product does and how it does it, which includes product requirements, specification, scope.

Example:

As an office worker, I want to be able to easily switch between standing and sitting, so that I prevent back pain and other health issues associated with prolonged periods of sitting at a computer.

+ + + + + +

+ +	+This user story follows a common template for user stories in the form of "As a <type_of_user>, I want <some_goal> so that <some_reason>." +

Ergonomic work space solution - a standing desk that allows switching between standing and sitting. The standing desk:

+
Is motorized, with a button a person can press to adjust the height; the height must span up to 150 cm to be usable also by people 200 cm tall.
+
+
Is made from easy-to-clean and durable material to withstand standard office conditions, such as spilled tea or scratches: table top - polyester, legs - steel.
+
+
Has large enough work surface to comfortably fit 2 monitors, one laptop docking station, small personal items.
+
+
Can hold the weight of 100 kg, such as standard office equipment and a person sitting on the desk.
+
+
Meets safety requirements per EU standards for office equipment.
+
+
Has attractive design to fit in modern office spaces.
+

+ + + + + +

+ +	+A use case like this can also include other ergonomic solutions, such as an adjustable sit-stand wall mount for monitors and compare their parameters, such as ease of installation, price, and ease of use. +

+ + + + + +

+ +

To fulfill their purpose, user stories must be defined based on customer needs. Therefore, they must be produced by customer-facing associates, such as product management or field teams, not by writers. Writers can only help polish the user stories if required.

If your team does not have user stories, do not write them yourselves. Instead, ask the stakeholders for your product to provide them to you.

User story-based docs

Docs developed to support a user story. For our purposes, user-story-based docs are the same as use-case-based docs.

Modular documentation

Documents structured into modules and assemblies.

+ + + + + +

+ +	+We do not use the terms topic or topic-based documentation because they are too ambiguous. A topic can mean a piece of documentation, a user story, or a short chunk of content. Therefore, topic-based can mean a number of things. +

+ +

Appendix C: Converting to modular documentation

If you have a monolithic, feature-based manual, you can convert it to a set of modular content based on user stories. This conversion workflow involves using the customer product lifecycle to define user stories for your product, and creating the assemblies and modules necessary to fit each user story.

The result is documentation that is more relevant for your readers, because it is based on real-world user stories (it tells them how to accomplish their goals), and modular (it can be assembled into whatever sets and formats they might need).

Prerequisites

+
You should understand what modular documentation is:
+
+
- +
  What Modular Documentation Is
  +
- +
  What Modular Documentation Is Not
  +
- +
  Modular Documentation Terminology
  +
+
+
+
You should understand the benefits of modular documentation.
+
+
For example, see Documentation based on user stories.
+
+
+
Find a user story and practice documenting it as an assembly.
+
+
This process of breaking down user stories into assemblies and modules is an essential element of modular documentation. You should be familiar with this process before attempting to do it for an entire feature-based book.
+
+
+
Your repository should be set up.
+
+
If you are using AsciiDoc, your repository should have a directory structure that supports modular documentation, and you should have a master.adoc file for each publication.
+
+

C.1. Overview of the customer product lifecycle

User stories are the basis of modular documentation. The modular documentation conversion workflow uses the customer product lifecycle to help you discover and develop the user stories that your documentation should include.

While all products are different, everyone tends to use them in a similar workflow that starts with the initial research to determine which product to use, includes implementing and managing the product, and ends when the product is no longer needed. This customer product lifecycle can be broken down into phases, each of which presents unique user information requirements (that is, the user needs different types of information at each phase of the lifecycle):

Plan: +
What information should be gathered and what decisions should be made (for example, design/deployment) before the customer can start installing the product?
+
Install: +
How does the customer install the product on each of the supported platforms?
+
Configure and verify: +
After the product is installed, what does the customer need to do to configure it to work in their environment? How do they test or verify that it is ready to put into production?
+
Develop and test: +
Does the customer need to develop any custom applications to connect the product to any of their existing infrastructure?
+
Manage: +
Once the product is in production, how does the customer customize and change it on a day-to-day basis?
+
Monitor and tune: +
Once the product is in production, how does the customer monitor its performance in order to know when changes are needed?
+
Upgrade and migrate: +
How does the customer upgrade to newer versions of the product?
+
Troubleshoot: +
How does the customer fix common problems they may encounter?
+

C.2. Defining user stories for your product

User stories provide the context and structure from which you can determine which assemblies and modules to create.

For more information about user stories, see Modular Documentation Terms and Definitions.

Ideally, well-defined user stories would already exist for the product you are documenting. For most writers, however, this ideal is not a reality. If you do not have any user stories from which to work, and you — as a writer — do not have all of the user information you would need to create the user stories yourself, how do you get started? This procedure provides a general approach that you can take.

Of course, every product differs in terms of tools, processes, team dynamics, and access to SMEs. Since you are most familiar with these aspects for your own team, you will need to adapt this general approach for your own team. Depending on your team structure, each step can be completed by either a writer or a collaboration between a writer and Content Strategist.

Procedure

+
Identify the key, top-level user stories for your product.
+
+
+
+
This step should typically be performed by the Content Strategist.
+
+
+
Start with the customer product lifecycle phases. If you have existing user stories, ask yourself which ones correspond to phases in the lifecycle. If you do not have existing user stories, create a user story for each lifecycle phase that applies to your product.
+
+
+
For more information, see Overview of the Customer Product Lifecycle.
+
+
+
For example, here is a top-level user story for the Configure and Verify phase of the customer product lifecycle:
+
+
+
Example 6. Creating top-level user stories
+
+
+
+
+
[Phase] Configure and Verify — [Top-level user story] As a system administrator, I want to configure PRODUCT so that it is ready for production.
+
+
+
+
+
+
+
+
+
Define the supporting user stories that are necessary to complete each of the top-level user stories.
+
+
+
+
This step should typically be a collaborative effort between the Content Strategist and the writer.
+
+
+
Each top-level user story represents a "phase" of the customer lifecycle. You should go through each phase and define the user stories needed to complete the phase. You will need to use your own knowledge and expertise of the product.
+
+
+
For example, for the Configure and Verify phase, users would need to know how to configure and set up each component or feature of the product to work in their environment. You could break it down like this:
+
+
+
Example 7. Creating second-level user stories
+
+
+
+
+
As a system administrator, I want to configure PRODUCT so that it is ready for production.
+
+
+
+
As a system administrator, I want to enable PRODUCT to make and accept connections so that remote peers can exchange data with PRODUCT.
+
+
+
As a system administrator, I want to secure PRODUCT so that it can communicate with remote peers securely.
+
+
+
As a system administrator, I want to set up logging so that error conditions can be diagnosed.
+
+
+
+
+
+
+
+
+
+
At this point, you should have a two-deep list of user stories.
+
+
+
+
+
Go back through the list and add any additional user stories that might be needed to complete any of the secondary user stories.
+
+
+
+
Depending on the product, one or two levels of user stories might be sufficient. For larger, more complex products, you might find yourself going multiple levels deep.
+
+
+
Be careful not to go too deep, however. At this stage, you are not defining every procedure or step needed to complete each user story. User stories represent user goals, so you should only need to go deeper if a secondary user story has multiple goals.
+
+
+
For example, under the "Configuring Product X" example in the previous step, the logging user story does not need any additional user stories — the goal cannot be reduced any further than it already is. On the other hand, the adding security settings user story might be able to go a bit deeper. Security is a goal in and of itself (users want their applications to be secure), but there are more specific goals users might have within it:
+
+
+
Example 8. Creating additional user stories
+
+
+
+
+
As a system administrator, I want to configure PRODUCT so that it is ready for production.
+
+
+
+
As a system administrator, I want to enable PRODUCT to make and accept connections so that remote peers can exchange data with PRODUCT.
+
+
+
As a system administrator, I want to secure PRODUCT so that it can communicate with remote peers securely.
+
+
+
+
As a system administrator, I want to add security certificates so that clients can be authenticated.
+
+
+
As a system administrator, I want to use my existing LDAP configuration so that clients can be authenticated.
+
+
+
+
+
+
As a system administrator, I want to set up logging so that error conditions can be diagnosed.
+
+
+
+
+
+
+
+
+
+
+
+
For each user story in your list, define the following:
+
+
+
+
- +
  What concepts does the user need to understand to complete the user story?
  +
  +
  These will become the concept modules for the assembly.
  +
  +
- +
  What are the procedures to complete the user story?
  +
  +
  These will become the procedure modules for the assembly.
  +
  +
- +
  Is there any reference information that the user might want to refer to when performing this user story?
  +
  +
  These will become reference modules.
  +
  +
+
+
+
Example 9. Breaking down user stories
+
+
+
+
+
As a system administrator, I want to configure PRODUCT so that it is ready for production.
+
+
+
+
As a system administrator, I want to enable PRODUCT to make and accept connections so that remote peers can exchange data with PRODUCT.
+
+
+
+
Concept: Types of connections
+
+
+
Procedure: Create "listeners" to accept incoming connections
+
+
+
Procedure: Create "connectors" to connect to outbound endpoints
+
+
+
Reference: Network connection configuration attributes
+
+
+
+
+
+
Additional user stories…
+
+
+
+
+
+
+
+
+
+
+

C.3. Creating assemblies

An assembly is a representation of a user story, so you need to create an assembly for each user story that you defined.

An assembly could represent an article, "chapter" in a book, or even an entire book. However, one of the benefits of modular documentation is that you do not need to worry about how the assembly will ultimately be used — each assembly represents a user goal, and once you create it, it can be "included" anywhere it is needed (a publication, within another assembly, and so on).

Procedure

+
Create an assembly file for each user story that you identified.
+
+
+
+
Follow the conventions for naming anchors and files. For example: assembly_designing-guided-decision-tables.adoc
+
+
+
+
+
For each top-level assembly file that you created, fill in the content.
+
+
For more information, see Assembly Guidelines.
+
+
+
Repeat the previous step for each second-level assembly.
+

C.4. Creating modules

After identifying and creating the assemblies, each assembly should identify the modules that you need to create.

Procedure

+
For each assembly that you created, create a module file for each module that is identified in the assembly.
+
+
+
+
Each assembly should already have the names of the modules that should be included in the assembly. Now you just need to create the actual files for those modules.
+
+
+
Follow the conventions for naming anchors and files. For example: proc_creating-guided-decision-tables.adoc
+
+
+
+
+
For each module file that you created, add content.
+
+
+
+
Use your existing, feature-based manual to get the content. Make sure to rewrite and rework it to fit the modular documentation module templates. For more information, see:
+
+
+
- +
  Concept Module Guidelines
  +
- +
  Procedure Module Guidelines
  +
- +
  Reference Module Guidelines
  +
+
+
+
+

C.5. Auditing your feature-based manual

In the process of adding content to the modules from your existing feature-based manual, it is likely that there is some existing content that did not fit into any of the user stories that you identified and thus was not pulled out. It is important to identify this content to ensure that it is no longer needed.

Procedure

+
Go through your existing feature-based manual and identify any content that you did not add to an assembly or module.
+
+
For each piece of content that you find, determine whether it is necessary.
+
+
+
+
If the content does not fit into a user story or assembly, then it stands to reason that it may not be necessary to complete any particular user goal. If this is the case, you should be able to discard it.
+
+
+
Example 10. Handling extraneous content
+
+
+
For example, many feature-based manuals contain detailed sections about how a particular feature works. This type of content, which is valuable in certain contexts, is not always necessary for user documentation — user goals generally involve doing something, not understanding how all the details work. When you encounter this type of content, ask yourself whether a user would need to understand it to accomplish any of their goals (planning, installing, configuring, managing, and so on). If the answer is no, then you can probably discard it.
+
+
+
+
+
On the other hand, it is also possible that the content is related to a user story that you have not considered. In that case, you should create the necessary assemblies and modules and add them to your modular doc.
+
+
+
+

+ + + \ No newline at end of file diff --git a/modular-docs-manual/.gitignore b/modular-docs-manual/.gitignore deleted file mode 100644 index 7c7f195..0000000 --- a/modular-docs-manual/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -build -master.html diff --git a/modular-docs-manual/README.md b/modular-docs-manual/README.md deleted file mode 100644 index 26c3e38..0000000 --- a/modular-docs-manual/README.md +++ /dev/null @@ -1 +0,0 @@ -The CCS Technical Writing Manual Project Source diff --git a/modular-docs-manual/common-content/attributes.adoc b/modular-docs-manual/common-content/attributes.adoc deleted file mode 100644 index c40e604..0000000 --- a/modular-docs-manual/common-content/attributes.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Use this file to define attributes shared by all content in the repo. - -:imagesdir: images -:toc: left -:toclevels: 3 -:numbered: -:sectanchors: -:sectlinks: -:experimental: - diff --git a/modular-docs-manual/content/modular-doc-manual.adoc b/modular-docs-manual/content/modular-doc-manual.adoc deleted file mode 100644 index 2db6ac2..0000000 --- a/modular-docs-manual/content/modular-doc-manual.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Chapter 1 -include::topics/introduction.adoc[leveloffset=+1] - -// Chapter 2 -include::topics/whats-new.adoc[leveloffset=+1] - -// Chapter 3 -include::topics/understanding-mod-docs.adoc[leveloffset=+1] - -// Chapter 4 -include::topics/writing-mod-docs.adoc[leveloffset=+1] - -// Appendices -[appendix] -include::topics/module_mod-docs-terms-definitions.adoc[leveloffset=+1] - -[appendix] -include::topics/mod-docs-examples.adoc[leveloffset=+1] - -[appendix] -include::topics/mod-docs-conversion.adoc[leveloffset=+1] diff --git a/modular-docs-manual/content/topics/creating_concept_modules.adoc b/modular-docs-manual/content/topics/creating_concept_modules.adoc deleted file mode 100644 index 31c4196..0000000 --- a/modular-docs-manual/content/topics/creating_concept_modules.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="creating-concept-modules"] -= Concept modules - -This section explains what a concept module is and provides recommended practices for writing concept modules. - -include::module_definition-concept.adoc[leveloffset=+1] - -include::module_guidelines-concept.adoc[leveloffset=+1] - -== Additional resources - -* Download the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc[concept module template (adoc file)] for new projects. -* For real-world examples of concept modules, see <>. diff --git a/modular-docs-manual/content/topics/creating_procedure_modules.adoc b/modular-docs-manual/content/topics/creating_procedure_modules.adoc deleted file mode 100644 index 397837b..0000000 --- a/modular-docs-manual/content/topics/creating_procedure_modules.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[id="con-creating-procedure-modules_{context}"] - -= Procedure modules - -Procedure modules explain how to do something. A procedure module contains numbered, step-by-step instructions to help users accomplish a single task. Sometimes those tasks include substeps. Procedure modules must include a title, a brief introduction, and one or more steps in the form of imperative statements. Procedure modules can also contain the following sections: - -* xref:limitations[] -* xref:prerequisites[] -* xref:verification[] -* xref:troubleshooting[] -* xref:next-steps[] -* xref:additional-resources[] - -Do not change or embellish these subheadings. Unless absolutely necessary, do not create additional subheadings. - -.Schema of a procedure module -image::procedure-diagram.png[] - -.Procedure title -The title of a procedure module is a gerund phrase, such as *Deploying OpenShift Container Platform*. - -.Procedure introduction -The procedure introduction is a short paragraph that provides an overview of the module. The introduction includes what the module will help the user do and why it will be beneficial to the user. It includes key words that relate to the module to maximize search engine optimization. - -The introduction typically provides context for the procedure, such as: - -* Why and where the user performs the procedure -* Special considerations specific to the procedure - -For details and examples, see the link:https://redhat-documentation.github.io/supplementary-style-guide/#shortdesc[Short descriptions] section in the Red Hat supplementary style guide. - -[id="prerequisites"] -.Prerequisites -This section is optional. Prerequisites are a bulleted list of conditions that must be satisfied before the user starts the procedure. Use a bulleted list for prerequisites and the plural heading *Prerequisites*, even if your procedure only has a single prerequisite. - -Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. - -Focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites. If a prerequisite applies to all of the procedures in a user story, consider listing the prerequisite in the assembly file. If you do this, consider including the prerequisite in the procedure module as a comment. - -[id="procedure"] -.Procedure -This section is required. The procedure consists of one or more steps required to complete the procedure. Each step describes one action written in the imperative form, for example, 'Do this action'. For single-step procedures, use an unnumbered bullet instead of a numbered list. - -NOTE: Not all numbered lists in documentation are procedures. You can also use numbered lists in any module type for non-procedural sequences, such as a process flow of system actions. - -[id="verification"] -.Verification -This section is optional. It provides the user with one or more steps to verify that the procedure provided the intended outcome, for example: - -* An example of expected command output or a pop-up window that the user receives when the procedure is successful -* Actions for the user to complete, such as entering a command, to determine the success or failure of the procedure - -[id="troubleshooting"] -.Troubleshooting -This section is optional and not used often. List any actions that can help with troubleshooting the procedure. This subsection should be short. Consider whether the information might be better in a separate troubleshooting procedure or as part of a reference module that contains other troubleshooting sections. - -[id="next-steps"] -.Next steps -This section is optional. Provide links to resources that contain instructions that might be useful to the user after they complete this procedure. - -NOTE: Do not use *Next steps* to provide a second list of instructions. - -[id="additional-resources"] -.Additional resources -This section is optional. The listed resources link to other material closely related to the contents of the module, such as other documentation resources, instructional videos, or labs. - -Focus on relevant resources that might interest the user. Do not list resources for completeness. If a resource applies to all of the modules in a user story, consider listing the resource in the Additional resources section of the assembly file. If you do this, consider including the resource in the procedure module as a comment. - - - -== Additional resources - -* Download the link:https://github.com/redhat-documentation/modular-docs/blob/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc[procedure module template (adoc file)] for new projects. -* For real-world examples of procedure modules, see <>. diff --git a/modular-docs-manual/content/topics/creating_reference_modules.adoc b/modular-docs-manual/content/topics/creating_reference_modules.adoc deleted file mode 100644 index 41796dd..0000000 --- a/modular-docs-manual/content/topics/creating_reference_modules.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="creating-reference-modules"] -= Reference modules - -This section explains what a reference module is and provides recommended practices for writing reference modules. - -include::module_definition-reference.adoc[leveloffset=+1] - -include::module_guidelines-reference.adoc[leveloffset=+1] - -== Additional resources - -* Download the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc[reference module template (adoc file)] for new projects. -* For real-world examples of reference modules, see <>. -* For advice on when to use lists and when to use tables, see link:https://medium.com/@heyoka/lets-bring-table-to-the-table-again-f1ae751159d5[Let’s bring to the table, again.] diff --git a/modular-docs-manual/content/topics/forming_assemblies.adoc b/modular-docs-manual/content/topics/forming_assemblies.adoc deleted file mode 100644 index 87dae52..0000000 --- a/modular-docs-manual/content/topics/forming_assemblies.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="forming-assemblies"] -= Forming assemblies - -This section explains what an assembly is and provides recommended practices for forming assemblies. - -include::module_definition-assembly.adoc[leveloffset=+1] - -include::module_guidelines-assembly.adoc[leveloffset=+1] - -== Additional resources - -* Download the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc[assembly template (adoc file)] for new projects. -* For real-world examples of assemblies, see <>. diff --git a/modular-docs-manual/content/topics/introduction.adoc b/modular-docs-manual/content/topics/introduction.adoc deleted file mode 100644 index 629a6c1..0000000 --- a/modular-docs-manual/content/topics/introduction.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="introduction_{context}"] -= Introduction to modular documentation - -This manual provides instructions on how to author modularly structured documentation based on user stories. The manual defines used terminology, describes components that form modular documentation, and instructs writers on how to use provided templates to turn user stories into modular documentation. - -IMPORTANT: As modular documentation imperatives continue to evolve, the details and recommendations in this guide might be modified. diff --git a/modular-docs-manual/content/topics/mod-docs-conversion.adoc b/modular-docs-manual/content/topics/mod-docs-conversion.adoc deleted file mode 100644 index f200be4..0000000 --- a/modular-docs-manual/content/topics/mod-docs-conversion.adoc +++ /dev/null @@ -1,38 +0,0 @@ -[id="converting-to-mod-doc"] -= Converting to modular documentation - -If you have a monolithic, feature-based manual, you can convert it to a set of modular content based on user stories. This conversion workflow involves using the customer product lifecycle to define user stories for your product, and creating the assemblies and modules necessary to fit each user story. - -The result is documentation that is more relevant for your readers, because it is based on real-world user stories (it tells them how to accomplish their goals), and modular (it can be assembled into whatever sets and formats they might need). - -.Prerequisites - -* You should understand what modular documentation is: -** xref:what-modular-documentation-is[What Modular Documentation Is] -** xref:what-modular-documentation-is-not[What Modular Documentation Is Not] -** xref:modular-docs-terms-definitions[Modular Documentation Terminology] - -* You should understand the benefits of modular documentation. -+ -For example, see link:https://opensource.com/article/17/6/documentation-based-user-stories[_Documentation based on user stories_]. - -* Find a user story and practice documenting it as an xref:assembly-guidelines[assembly]. -+ -This process of breaking down user stories into assemblies and modules is an essential element of modular documentation. You should be familiar with this process before attempting to do it for an entire feature-based book. - -* Your repository should be set up. -+ -If you are using AsciiDoc, your repository should have a directory structure that supports modular documentation, and you should have a `master.adoc` file for each publication. -+ -// Add an xref to Issue #4 when it's available (https://github.com/redhat-documentation/modular-docs/issues/4) - - -include::module_customer-product-lifecycle.adoc[leveloffset=+1] - -include::module_defining-user-stories.adoc[leveloffset=+1] - -include::module_creating-assemblies.adoc[leveloffset=+1] - -include::module_creating-modules.adoc[leveloffset=+1] - -include::module_auditing.adoc[leveloffset=+1] diff --git a/modular-docs-manual/content/topics/mod-docs-examples.adoc b/modular-docs-manual/content/topics/mod-docs-examples.adoc deleted file mode 100644 index 95bc5fe..0000000 --- a/modular-docs-manual/content/topics/mod-docs-examples.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="appendix-examples"] -= Module and assembly examples - -include::module_mod-docs-concept-examples.adoc[leveloffset=+1] - -include::module_mod-docs-procedure-examples.adoc[leveloffset=+1] - -include::module_mod-docs-reference-examples.adoc[leveloffset=+1] - -include::module_mod-docs-assembly-examples.adoc[leveloffset=+1] diff --git a/modular-docs-manual/content/topics/module_anchor-and-file-names-concept.adoc b/modular-docs-manual/content/topics/module_anchor-and-file-names-concept.adoc deleted file mode 100644 index 4d8146a..0000000 --- a/modular-docs-manual/content/topics/module_anchor-and-file-names-concept.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id="module_anchor-and-file-names-concept"] -= File names and anchors - -To optimize modular documentation, follow these guidelines for naming files and creating anchors: - -.File names -Create assembly and module file names that accurately and closely reflect the title of the assembly or module. Create file names with the format `prefix-filename.adoc` or `prefix_filename.adoc` where `prefix` is one of the following module prefixes: - -* `con`: Concept module prefix -* `proc`: Procedure module prefix -* `ref`: Reference module prefix -* `assembly`: Assembly module prefix - -.Examples -* `con-guided-decision-tables.adoc` (Concept module) -* `con_guided-decision-tables.adoc` (Concept module) -* `proc-creating-guided-decision-tables.adoc` (Procedure module for creating) -* `proc_creating-guided-decision-tables.adoc` (Procedure module for creating) -* `ref-guided-decision-table-examples.adoc` (Reference module with examples) -* `ref_guided-decision-table-examples.adoc` (Reference module with examples) -* `assembly-designing-guided-decision-tables.adoc` (Assembly of guided decision table modules) -* `assembly_designing-guided-decision-tables.adoc` (Assembly of guided decision table modules) - - -[NOTE] -==== -Do not include special characters in file names. Ensure that all members of your team use the same file naming conventions. -==== - -These file naming guidelines are optional but highly recommended. However, if your team does not include the module prefixes in file names followed by either a hyphen (-) or an underscore (_), include one of the following variables in each file before the anchor ID: - -[source,asciidoc] ----- -:_mod-docs-content-type: ASSEMBLY -:_mod-docs-content-type: PROCEDURE -:_mod-docs-content-type: CONCEPT -:_mod-docs-content-type: REFERENCE -:_mod-docs-content-type: SNIPPET ----- - -.Anchors -At the top of every module, provide an anchor in the format `+++[id="filename_{context}"]+++` where `filename` is the exact name of the file, without the file extension (`.adoc`) and a module prefix. Module anchors are necessary so that Asciidoctor can identify the module when the module is reused or cross-referenced. The `context` variable is defined in each assembly module, such as `:context: my-context-value`. When you build an assembly, the value of the `context` variable replaces `context` in each module anchor ID and is displayed in the generated URL. - -[source,asciidoc] ----- -[id="filename_{context}"] -= Module heading - -The first sentence of the topic. ----- - -.Example 1. Concept module -[source,asciidoc] ----- -[id="guided-decision-tables_{context}"] -= Guided decision tables - -The guided decision tables feature works similarly to… ----- - -.Example 2. Procedure module -[source,asciidoc] ----- -[id="creating-guided-decision-tables_{context}"] -= Creating guided decision tables - -You can use guided decision tables to… ----- - -[NOTE] -==== -The previously defined anchor format is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced correctly. For details, see xref:reusing-modules[Reusing modules in assemblies]. Other anchor formats include `+++[[anchor-name]]+++` and `+++[#anchor-name]+++`, but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time. -==== - - - -.Additional resources - -* link:https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] diff --git a/modular-docs-manual/content/topics/module_auditing.adoc b/modular-docs-manual/content/topics/module_auditing.adoc deleted file mode 100644 index f4565cf..0000000 --- a/modular-docs-manual/content/topics/module_auditing.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="auditing"] -= Auditing your feature-based manual - -In the process of adding content to the modules from your existing feature-based manual, it is likely that there is some existing content that did not fit into any of the user stories that you identified and thus was not pulled out. It is important to identify this content to ensure that it is no longer needed. - -.Procedure - -. Go through your existing feature-based manual and identify any content that you did not add to an assembly or module. - -. For each piece of content that you find, determine whether it is necessary. -+ --- -If the content does not fit into a user story or assembly, then it stands to reason that it may not be necessary to complete any particular user goal. If this is the case, you should be able to discard it. - -.Handling extraneous content -==== -For example, many feature-based manuals contain detailed sections about how a particular feature works. This type of content, which is valuable in certain contexts, is not always necessary for user documentation -- user goals generally involve _doing_ something, not understanding how all the details work. When you encounter this type of content, ask yourself whether a user would need to understand it to accomplish any of their goals (planning, installing, configuring, managing, and so on). If the answer is no, then you can probably discard it. -==== - -On the other hand, it is also possible that the content is related to a user story that you have not considered. In that case, you should create the necessary assemblies and modules and add them to your modular doc. --- diff --git a/modular-docs-manual/content/topics/module_creating-assemblies.adoc b/modular-docs-manual/content/topics/module_creating-assemblies.adoc deleted file mode 100644 index d1d7c9b..0000000 --- a/modular-docs-manual/content/topics/module_creating-assemblies.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="creating-assemblies"] -= Creating assemblies - -An assembly is a representation of a user story, so you need to create an assembly for each user story that you defined. - -An assembly could represent an article, "chapter" in a book, or even an entire book. However, one of the benefits of modular documentation is that you do not need to worry about how the assembly will ultimately be used -- each assembly represents a user goal, and once you create it, it can be "included" anywhere it is needed (a publication, within another assembly, and so on). - -.Procedure - -. Create an assembly file for each user story that you identified. -+ --- -Follow the conventions for xref:module_anchor-and-file-names-concept[naming anchors and files]. For example: `assembly_designing-guided-decision-tables.adoc` --- - -. For each top-level assembly file that you created, fill in the content. -+ -For more information, see xref:assembly-guidelines[Assembly Guidelines]. - -. Repeat the previous step for each second-level assembly. diff --git a/modular-docs-manual/content/topics/module_creating-modules.adoc b/modular-docs-manual/content/topics/module_creating-modules.adoc deleted file mode 100644 index ad1e9cb..0000000 --- a/modular-docs-manual/content/topics/module_creating-modules.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="creating-modules"] -= Creating modules - -After identifying and creating the assemblies, each assembly should identify the modules that you need to create. - -.Procedure - -. For each assembly that you created, create a module file for each module that is identified in the assembly. -+ --- -Each assembly should already have the names of the modules that should be included in the assembly. Now you just need to create the actual files for those modules. - -Follow the conventions for xref:module_anchor-and-file-names-concept[naming anchors and files]. For example: `proc_creating-guided-decision-tables.adoc` --- -. For each module file that you created, add content. -+ --- -Use your existing, feature-based manual to get the content. Make sure to rewrite and rework it to fit the modular documentation module templates. For more information, see: - -* xref:concept-module-guidelines[Concept Module Guidelines] -* xref:procedure-module-guidelines[Procedure Module Guidelines] -* xref:reference-module-guidelines[Reference Module Guidelines] --- diff --git a/modular-docs-manual/content/topics/module_customer-product-lifecycle.adoc b/modular-docs-manual/content/topics/module_customer-product-lifecycle.adoc deleted file mode 100644 index e965b56..0000000 --- a/modular-docs-manual/content/topics/module_customer-product-lifecycle.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="customer-product-lifecycle"] -= Overview of the customer product lifecycle - -User stories are the basis of modular documentation. The modular documentation conversion workflow uses the _customer product lifecycle_ to help you discover and develop the user stories that your documentation should include. - -While all products are different, everyone tends to use them in a similar workflow that starts with the initial research to determine which product to use, includes implementing and managing the product, and ends when the product is no longer needed. This customer product lifecycle can be broken down into phases, each of which presents unique user information requirements (that is, the user needs different types of information at each phase of the lifecycle): - -Plan:: What information should be gathered and what decisions should be made (for example, design/deployment) before the customer can start installing the product? -Install:: How does the customer install the product on each of the supported platforms? -Configure and verify:: After the product is installed, what does the customer need to do to configure it to work in their environment? How do they test or verify that it is ready to put into production? -Develop and test:: Does the customer need to develop any custom applications to connect the product to any of their existing infrastructure? -Manage:: Once the product is in production, how does the customer customize and change it on a day-to-day basis? -Monitor and tune:: Once the product is in production, how does the customer monitor its performance in order to know when changes are needed? -Upgrade and migrate:: How does the customer upgrade to newer versions of the product? -Troubleshoot:: How does the customer fix common problems they may encounter? diff --git a/modular-docs-manual/content/topics/module_defining-user-stories.adoc b/modular-docs-manual/content/topics/module_defining-user-stories.adoc deleted file mode 100644 index d01dd8b..0000000 --- a/modular-docs-manual/content/topics/module_defining-user-stories.adoc +++ /dev/null @@ -1,96 +0,0 @@ -[id="defining-user-stories"] -= Defining user stories for your product - -User stories provide the context and structure from which you can determine which assemblies and modules to create. - -For more information about user stories, see xref:modular-docs-terms-definitions[Modular Documentation Terms and Definitions]. - -Ideally, well-defined user stories would already exist for the product you are documenting. For most writers, however, this ideal is not a reality. If you do not have any user stories from which to work, and you -- as a writer -- do not have all of the user information you would need to create the user stories yourself, how do you get started? This procedure provides a general approach that you can take. - -Of course, every product differs in terms of tools, processes, team dynamics, and access to SMEs. Since you are most familiar with these aspects for your own team, you will need to adapt this general approach for your own team. Depending on your team structure, each step can be completed by either a writer or a collaboration between a writer and Content Strategist. - -.Procedure - -. Identify the key, top-level user stories for your product. -+ --- -This step should typically be performed by the Content Strategist. - -Start with the customer product lifecycle phases. If you have existing user stories, ask yourself which ones correspond to phases in the lifecycle. If you do not have existing user stories, create a user story for each lifecycle phase that applies to your product. - -For more information, see xref:customer-product-lifecycle[Overview of the Customer Product Lifecycle]. - -For example, here is a top-level user story for the _Configure and Verify_ phase of the customer product lifecycle: - -.Creating top-level user stories -==== -* [Phase] Configure and Verify -- [Top-level user story] As a system administrator, I want to configure _PRODUCT_ so that it is ready for production. -==== --- - -. Define the supporting user stories that are necessary to complete each of the top-level user stories. -+ --- -This step should typically be a collaborative effort between the Content Strategist and the writer. - -Each top-level user story represents a "phase" of the customer lifecycle. You should go through each phase and define the user stories needed to complete the phase. You will need to use your own knowledge and expertise of the product. - -For example, for the _Configure and Verify_ phase, users would need to know how to configure and set up each component or feature of the product to work in their environment. You could break it down like this: - -.Creating second-level user stories -==== -* As a system administrator, I want to configure _PRODUCT_ so that it is ready for production. -** As a system administrator, I want to enable _PRODUCT_ to make and accept connections so that remote peers can exchange data with _PRODUCT_. -** As a system administrator, I want to secure _PRODUCT_ so that it can communicate with remote peers securely. -** As a system administrator, I want to set up logging so that error conditions can be diagnosed. -==== - -At this point, you should have a two-deep list of user stories. --- - -. Go back through the list and add any additional user stories that might be needed to complete any of the secondary user stories. -+ --- -Depending on the product, one or two levels of user stories might be sufficient. For larger, more complex products, you might find yourself going multiple levels deep. - -Be careful not to go too deep, however. At this stage, you are not defining every procedure or step needed to complete each user story. User stories represent user goals, so you should only need to go deeper if a secondary user story has multiple goals. - -For example, under the "Configuring Product X" example in the previous step, the logging user story does not need any additional user stories -- the goal cannot be reduced any further than it already is. On the other hand, the adding security settings user story might be able to go a bit deeper. Security is a goal in and of itself (users want their applications to be secure), but there are more specific goals users might have within it: - -.Creating additional user stories -==== -* As a system administrator, I want to configure _PRODUCT_ so that it is ready for production. -** As a system administrator, I want to enable _PRODUCT_ to make and accept connections so that remote peers can exchange data with _PRODUCT_. -** As a system administrator, I want to secure _PRODUCT_ so that it can communicate with remote peers securely. -*** As a system administrator, I want to add security certificates so that clients can be authenticated. -*** As a system administrator, I want to use my existing LDAP configuration so that clients can be authenticated. -** As a system administrator, I want to set up logging so that error conditions can be diagnosed. -==== --- - -. For each user story in your list, define the following: -+ --- -* What concepts does the user need to understand to complete the user story? -+ -These will become the concept modules for the assembly. - -* What are the procedures to complete the user story? -+ -These will become the procedure modules for the assembly. - -* Is there any reference information that the user might want to refer to when performing this user story? -+ -These will become reference modules. - -.Breaking down user stories -==== -* As a system administrator, I want to configure _PRODUCT_ so that it is ready for production. -** As a system administrator, I want to enable _PRODUCT_ to make and accept connections so that remote peers can exchange data with _PRODUCT_. -*** Concept: Types of connections -*** Procedure: Create "listeners" to accept incoming connections -*** Procedure: Create "connectors" to connect to outbound endpoints -*** Reference: Network connection configuration attributes -** _Additional user stories..._ -==== --- diff --git a/modular-docs-manual/content/topics/module_definition-assembly.adoc b/modular-docs-manual/content/topics/module_definition-assembly.adoc deleted file mode 100644 index 67da0e3..0000000 --- a/modular-docs-manual/content/topics/module_definition-assembly.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[id="assembly-definition"] -= Assembly definition - -An assembly is a collection of modules that describes how to accomplish a user story. See also <>. diff --git a/modular-docs-manual/content/topics/module_definition-concept.adoc b/modular-docs-manual/content/topics/module_definition-concept.adoc deleted file mode 100644 index 1bf9e75..0000000 --- a/modular-docs-manual/content/topics/module_definition-concept.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[id="concept-module-definition"] -= Concept module definition - -A concept module is an "understand" module. Concept modules give the user descriptions and explanations needed to understand and use a product. diff --git a/modular-docs-manual/content/topics/module_definition-reference.adoc b/modular-docs-manual/content/topics/module_definition-reference.adoc deleted file mode 100644 index 6d66e76..0000000 --- a/modular-docs-manual/content/topics/module_definition-reference.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="reference-module-definition"] -= Reference module definition - -Reference modules provide data that users might want to look up, but do not need to remember. - -.Common documentation examples of reference modules -==== -* A list of commands that users can use with an application -* A table of configuration files with definitions and usage examples -* A list of default settings for a product -==== - -.Reference modules explained using a real-life example -==== -For documentation on how to cross the road, you could create these modules: - -* Concept modules: -** What are roads -** What are crossings - -* Procedure modules: -** How to put one foot in front of another -** How to use pedestrian traffic lights -** How to see if the road is clear for crossing - -* Reference modules: -** Crossing signals -** Common crosswalk pavement markings -** Crossing laws by country -==== diff --git a/modular-docs-manual/content/topics/module_guidelines-assembly.adoc b/modular-docs-manual/content/topics/module_guidelines-assembly.adoc deleted file mode 100644 index 5c0ff11..0000000 --- a/modular-docs-manual/content/topics/module_guidelines-assembly.adoc +++ /dev/null @@ -1,56 +0,0 @@ -[id="assembly-guidelines"] -= Assembly guidelines - -The required parts of an assembly are the introduction and modules. Optionally, an assembly can also include prerequisites and additional resources. - -[discrete] -== Assembly title - -If the assembly describes a task and includes one or more procedure modules, start the title with a verb in the gerund form, such as Creating or Configuring, for example _Encrypting block devices using LUKS_. If the assembly does not include any procedure modules, use a noun phrase, for example _Red Hat Process Automation Manager API reference_. - -[discrete] -== Assembly introduction - -The introduction explains what the user accomplishes by working through the assembled modules. It typically provides context for the assembly. - -Consider rewording the user story to write the assembly introduction, for example: - -* User story: As an administrator, I want to provide external identity, authentication and authorization services for my Atomic Host, so that users from external identity sources can access the Atomic Host. -* Assembly introduction: As a system administrator, you can use SSSD in a container to provide external identity, authentication, and authorization services for the Atomic Host system. This enables users from external identity sources to authenticate to the Atomic Host. - -For details and examples, see the link:https://redhat-documentation.github.io/supplementary-style-guide/#shortdesc[Short descriptions] section in the Red Hat supplementary style guide. - -[discrete] -== Assembly prerequisites - -Prerequisites are conditions that must be satisfied before the user can start following the assembly and are applicable to all the modules in the assembly. - -Use the second level heading syntax for the Prerequisites section in the assembly so that it is displayed in the table of contents and is consistent with the Additional resources or Next steps sections in the assembly. - -// [bhardest] - We have a lot of xref-ing in these guidelines. A better approach might be to create a "snippets" .adoc file with snippets of common content (for example, the content about writing prerequisites, which applies to multiple sections). Then we can just include the relevant content from the snippets file wherever it's needed. -// [asteflova] - Let's do this after we finish reviewing the guidelines for procedures and assemblies. -// [sterobin] - I removed the cross-ref to the procedure "Writing prerequisites" for now because it provided no value and the id for that linked section needed to be removed anyway (should only be linking to modules, not module sub-headings). This clearly now provides little information, but based on the above comments, we should be looking into a better structure all around in this doc for describing the prereq, intro, body components that apply universally. - -[discrete] -== Assembly modules - -To include modules in an assembly, use the Asciidoc link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include directive]. Use any combination of concept, procedure, and reference modules that fulfills the purpose of the assembly. Use the `leveloffset` attribute to set the hierarchy of the module relative to the assembly, as shown in the following example: - -.Level offset for module files ----- -file1.adoc[leveloffset=+1] -file2.adoc[leveloffset=+2] -file3.adoc[leveloffset=+3] ----- - -All module and assembly titles must use the H1 heading designation, such as `= My heading`. - -[discrete] - - -== Next steps and Additional resources -These sections are optional. If you use both *Next steps* and *Additional resources*, list *Next steps* first. The listed resources link to other material closely related to the contents of the module, such as other documentation resources, instructional videos, or labs. - -Focus on relevant resources that might interest the user. Do not list resources for completeness. If a resource applies to all of the modules in a user story, consider listing the resource in the Additional resources section of the assembly file. If you do this, consider including the resource in the procedure module as a comment. - -NOTE: If you use *Next steps* or *Additional resources* in an assembly file, check whether the last module in the assembly also has *Next steps* or *Additional resources*. If so, view the rendered HTML and consider rewriting or reorganizing the assembly. diff --git a/modular-docs-manual/content/topics/module_guidelines-concept.adoc b/modular-docs-manual/content/topics/module_guidelines-concept.adoc deleted file mode 100644 index 668a7b3..0000000 --- a/modular-docs-manual/content/topics/module_guidelines-concept.adoc +++ /dev/null @@ -1,75 +0,0 @@ -[id="concept-module-guidelines"] -= Concept module guidelines - -The core requirement for a concept module is explaining the idea, or concept. -A concept module requires a short introduction and optionally, can also include additional resources. - -When planning a concept module, look at nouns in related procedure modules and assemblies to find the concepts to explain to users. -Explain only things that are visible to users. -Even if a concept is interesting, it probably does not require an explanation if it is not visible to users. - -image::concept-diagram.png[] - -[discrete] -== Concept introduction - -The introduction to a concept module is a single, concise paragraph that provides a short overview of the module. -A short description makes the module more usable because users can quickly determine whether the concept is useful without having to read the entire module. - -The introduction typically answers the following questions: - -* What is the concept? -* Why should the user care about the concept? - -For details and examples, see the link:https://redhat-documentation.github.io/supplementary-style-guide/#shortdesc[Short descriptions] section in the Red Hat supplementary style guide. - -[discrete] -== Concept body - -The concept body describes the subject of the concept module. - -Apart from paragraphs, you can use other AsciiDoc elements, such as lists, tables, or examples. -Consider including graphics or diagrams to speed up the understanding of the concept. - -Avoid including instructions to perform an action. Action items belong in procedure modules. However, in some cases a concept or reference module can include suggested actions when those actions are simple, are highly dependent on the context of the module, and have no place in any procedure module. In such cases, ensure that the heading of the concept or reference remains a noun phrase and not a gerund. For example, see link:https://access.redhat.com/documentation/en-us/red_hat_process_automation_manager/7.9/html-single/developing_decision_services_in_red_hat_process_automation_manager/index#bound_variables_in_patterns_and_constraints[ -"Bound variables in patterns and constraints"] and the sections that follow it. These concept and reference modules contain actions that are not suitable for standalone procedure modules but are relevant actions to understand in the context of the concept or reference being described. - -See also link:https://informationmapping.com/blogs/news/the-dita-topic-types-square-pegs-and-round-holes?_pos=1&_sid=45011393d&_ss=r[The DITA Topic Types] at _informationmapping.com_ for more information about different types of conceptual information: principle, concept, structure, process, and fact. - -If the concept module is large and complex, consider splitting the concept module into multiple standalone concept modules. If you cannot split the module into meaningful standalone modules, consider using subheadings in the module to structure the content for improved reader navigation. If you use subheadings in a concept module, you can add the `[discrete]` tag to exclude each subheading from the table of contents, if needed. However, in many cases, subheadings are helpful to include in the table of contents to improve content searchability. - -The following examples illustrate a discrete and a standard subheading: - -.Example discrete subheading excluded from table of contents -[source] ----- -= My concept module - -Concept introduction and body - -[discrete] -== My concept module subheading - -More concept body content ----- - -.Example subheading included in table of contents -[source] ----- -= My concept module - -Concept introduction and body - -== My concept module subheading - -More concept body content ----- - -NOTE: You can use subheadings in concept or reference modules, but not in procedure modules. - -[discrete] -== Concept additional resources - -The optional additional resources list links to other material closely related to the contents of the concept module, for example, other documentation resources. - -Focus on relevant resources that might interest the user. Do not list resources for completeness. diff --git a/modular-docs-manual/content/topics/module_guidelines-reference.adoc b/modular-docs-manual/content/topics/module_guidelines-reference.adoc deleted file mode 100644 index 3077aa0..0000000 --- a/modular-docs-manual/content/topics/module_guidelines-reference.adoc +++ /dev/null @@ -1,55 +0,0 @@ -[id="reference-module-guidelines"] -= Reference module guidelines - -The required part of a reference module is the reference data. -A reference module requires a short introduction. - -[discrete] -== Reference introduction - -The introduction to a reference module is a single, concise paragraph that provides a short overview of the module. A short description makes the module more usable because users can quickly determine whether the reference is useful without having to read the entire module. - -For details and examples, see the link:https://redhat-documentation.github.io/supplementary-style-guide/#shortdesc[Short descriptions] section in the Red Hat supplementary style guide. - -[discrete] -== Reference body - -A reference module has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want. - -To make the reference data easier to scan, organize it in a logical order (such as alphabetically) or as a table. AsciiDoc markup to consider for reference data: - -* link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#lists[Lists] (unordered, labeled) -* link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#tables[Tables] - -If you have a large volume of the same type of information to document, use a structure into which the information details can fit, and then document each logical unit of information as one reference module. For example, think of man pages, which document very different information details, but which still use consistent titles and formats to present those details in a uniform information structure. - -If the reference module is large and complex, consider splitting the reference module into multiple standalone reference modules. If you cannot split the module into meaningful standalone modules, consider using subheadings in the module to structure the content for improved reader navigation. If you use subheadings in a reference module, you can add the `[discrete]` tag to exclude each subheading from the table of contents, if needed. However, in many cases, subheadings are helpful to include in the table of contents to improve content searchability. - -The following examples illustrate a discrete and a standard subheading: - -.Example discrete subheading excluded from table of contents -[source] ----- -= My reference module - -Reference introduction and body - -[discrete] -== My reference module subheading - -More reference body content ----- - -.Example subheading included in table of contents -[source] ----- -= My reference module - -Reference introduction and body - -== My reference module subheading - -More reference body content ----- - -NOTE: You can use subheadings in concept or reference modules, but not in procedure modules. diff --git a/modular-docs-manual/content/topics/module_mod-docs-assembly-examples.adoc b/modular-docs-manual/content/topics/module_mod-docs-assembly-examples.adoc deleted file mode 100644 index 7196f21..0000000 --- a/modular-docs-manual/content/topics/module_mod-docs-assembly-examples.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="modular-docs-assembly-examples"] -= Assembly examples - -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/securing_networks/assembly_using-secure-communications-between-two-systems-with-openssh_securing-networks[Using secure communications between two systems with OpenSSH] - -link:https://access.redhat.com/documentation/en-us/red_hat_process_automation_manager/7.8/html-single/packaging_and_deploying_a_red_hat_process_automation_manager_project/index[Packaging and deploying a Red Hat Process Automation Manager project] - -link:https://access.redhat.com/documentation/en-us/red_hat_process_automation_manager/7.8/html-single/designing_a_decision_service_using_spreadsheet_decision_tables/index[Designing a decision service using spreadsheet decision tables] - diff --git a/modular-docs-manual/content/topics/module_mod-docs-concept-examples.adoc b/modular-docs-manual/content/topics/module_mod-docs-concept-examples.adoc deleted file mode 100644 index 73f0815..0000000 --- a/modular-docs-manual/content/topics/module_mod-docs-concept-examples.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="modular-docs-concept-examples"] -= Concept module examples - -link:https://access.redhat.com/documentation/en-us/red_hat_process_automation_manager/7.13/html/integrating_red_hat_process_automation_manager_with_other_products_and_components/bus_app_business-applications[Red Hat Process Automation Manager Spring Boot business applications] - -link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.5/html/architecture/cicd_gitops#cicd_gitops_methodology[The GitOps methodology and practice] - -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/using_selinux/getting-started-with-selinux_using-selinux#introduction-to-selinux_getting-started-with-selinux[Introduction to SELinux] diff --git a/modular-docs-manual/content/topics/module_mod-docs-procedure-examples.adoc b/modular-docs-manual/content/topics/module_mod-docs-procedure-examples.adoc deleted file mode 100644 index 21f4357..0000000 --- a/modular-docs-manual/content/topics/module_mod-docs-procedure-examples.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="modular-docs-procedure-examples"] -= Procedure module examples - -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/security_hardening/assembly_blocking-and-allowing-applications-using-fapolicyd_security-hardening#marking-files-as-trusted-using-an-additional-source-of-trust_assembly_blocking-and-allowing-applications-using-fapolicyd[Marking files as trusted using an additional source of trust] - -link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.5/html/installing/installing-mirroring-installation-images#installation-mirror-repository_installing-mirroring-installation-images[Mirroring the OpenShift Container Platform image repository] - -link:https://access.redhat.com/documentation/en-us/red_hat_ceph_storage/3/html/container_guide/administering-ceph-clusters-that-run-in-containers#purging-clusters-deployed-by-ansible[Purging Clusters Deployed by Ansible] diff --git a/modular-docs-manual/content/topics/module_mod-docs-reference-examples.adoc b/modular-docs-manual/content/topics/module_mod-docs-reference-examples.adoc deleted file mode 100644 index 4c7ec7e..0000000 --- a/modular-docs-manual/content/topics/module_mod-docs-reference-examples.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="modular-docs-reference-examples"] -= Reference module examples - - -link:https://access.redhat.com/documentation/en-us/red_hat_ceph_storage/3/html/container_guide/changes-in-ansible-variables-between-version-2-and-3-container[Changes in Ansible Variables Between Version 2 and 3] - -link:https://access.redhat.com/documentation/en-us/red_hat_amq_broker/7.11/html/deploying_amq_broker_on_openshift/reference-broker-ocp-broker-ocp#addressing-crd_broker-ocp[Address Custom Resource configuration reference] - -link:https://access.redhat.com/documentation/en-us/red_hat_process_automation_manager/7.8/html/interacting_with_red_hat_process_automation_manager_using_kie_apis/ejb-api-con_kie-apis#ejb-api-services-ref_kie-apis[Supported EJB services] diff --git a/modular-docs-manual/content/topics/module_mod-docs-terms-definitions.adoc b/modular-docs-manual/content/topics/module_mod-docs-terms-definitions.adoc deleted file mode 100644 index 75c3599..0000000 --- a/modular-docs-manual/content/topics/module_mod-docs-terms-definitions.adoc +++ /dev/null @@ -1,57 +0,0 @@ -[id="modular-docs-terms-definitions"] -= Modular documentation terms and definitions - -Assembly:: A collection of several modules combined into a larger piece of text, preceded by an introduction that explains the purpose of the assembly. -+ -The docs realization of a _user story_. - -Module:: An independent, self-contained chunk of information with a well-organized structure. Each module is information that a reader can understand and use by itself. A writer can use a module as a standalone article or as part of a larger body of work (an "Assembly"). A module does not depend on other documents, but it can refer the reader to other documents as additional resources. Because a module is self-contained, it must have a clear title that briefly and clearly summarizes the subject of the module. Moreover, because modules are written as context-free elements independent of other modules, they are re-usable. One module can be part of multiple assemblies. -+ -Concept module::: Explains a concept; for example, not action-based. -Procedure module::: Describes steps to perform an action. -Reference Module::: Presents detailed reference material, for example, command syntax. - -User story:: A short description of something the user does to achieve a goal. -+ -Example: As an administrator, I want to set up authentication to a critical system in my infrastructure, such as a gateway VPN, or accounting system to only allow users authenticated through strong authentication methods, such as two-factor authentication. -+ -As opposed to a _use case_, which is a description of interactions between the system and the user or other systems. -+ -.Contrasting user stories and use cases -[grid="rows"] -[options="header",width=100%,cols="10%s,45%a,45%a"] -|=== -| | User Story | Use Cases -| Definitions: | A short description of something the user does to achieve a goal. | A description of interactions between the system and the user, components of the system, or the system and other systems. -| Views the situation from: | The perspective of a user. | The perspective of a product and its features. -| Focuses on: | The outcome as perceived by the user. | What the product does and how it does it, which includes product requirements, specification, scope. -| Example: -| As an office worker, I want to be able to easily switch between standing and sitting, so that I prevent back pain and other health issues associated with prolonged periods of sitting at a computer. - -NOTE: This user story follows a common template for user stories in the form of "As a , I want so that ." - -| Ergonomic work space solution - a standing desk that allows switching between standing and sitting. The standing desk: - -* Is motorized, with a button a person can press to adjust the height; the height must span up to 150 cm to be usable also by people 200 cm tall. -* Is made from easy-to-clean and durable material to withstand standard office conditions, such as spilled tea or scratches: table top - polyester, legs - steel. -* Has large enough work surface to comfortably fit 2 monitors, one laptop docking station, small personal items. -* Can hold the weight of 100 kg, such as standard office equipment and a person sitting on the desk. -* Meets safety requirements per EU standards for office equipment. -* Has attractive design to fit in modern office spaces. - -NOTE: A use case like this can also include other ergonomic solutions, such as an adjustable sit-stand wall mount for monitors and compare their parameters, such as ease of installation, price, and ease of use. - -|=== -+ -[IMPORTANT] -==== -To fulfill their purpose, user stories must be defined based on customer needs. Therefore, they must be produced by customer-facing associates, such as product management or field teams, not by writers. Writers can only help polish the user stories if required. - -If your team does not have user stories, do not write them yourselves. Instead, ask the stakeholders for your product to provide them to you. -==== - -User story-based docs:: Docs developed to support a user story. For our purposes, user-story-based docs are the same as use-case-based docs. - -Modular documentation:: Documents structured into modules and assemblies. - -NOTE: We do not use the terms _topic_ or _topic-based documentation_ because they are too ambiguous. A _topic_ can mean a piece of documentation, a user story, or a short chunk of content. Therefore, topic-based can mean a number of things. diff --git a/modular-docs-manual/content/topics/module_modular-documentation-repositories.adoc b/modular-docs-manual/content/topics/module_modular-documentation-repositories.adoc deleted file mode 100644 index ed6afd6..0000000 --- a/modular-docs-manual/content/topics/module_modular-documentation-repositories.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[id="modular-documentation-repositories"] -= Modular documentation repositories - -Due to many factors that determine repository design for individual products, these modular documentation guidelines do not provide a strict documentation repository template. - -For a general repository structure used by documentation teams at Red Hat, see the example documentation repository and `README` file in the https://github.com/redhat-documentation/modular-docs/tree/mod-doc-repo-example[`mod-doc-repo-example`] branch in this repository. diff --git a/modular-docs-manual/content/topics/module_nesting-assemblies.adoc b/modular-docs-manual/content/topics/module_nesting-assemblies.adoc deleted file mode 100644 index 8a34a79..0000000 --- a/modular-docs-manual/content/topics/module_nesting-assemblies.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="nesting-assemblies"] -= Nesting assemblies in assemblies - -When you set the `:context:` variable in an assembly, the variable continues to be set to the same value in the rest of the document even after the assembly itself ends. This causes problems if you include an assembly in another assembly. - -If there is, for example, an _Additional Resources_ section in the inner, included assembly as well as in the outer, including assembly after the include statements, the ID of the second one gets overwritten with the `:context:` variable of the included assembly. This causes duplicate IDs, which lead to build-time errors like: - ----- -asciidoctor: WARNING: 1.adoc: line 19: id assigned to section already in use: additional-resources-2 ----- - -.Nested assemblies with a duplicate ID -==== -image::nested-assemblies-error.png[alt=Nested Assemblies with a Duplicate ID,width=500] -==== - -To solve this problem, restore the `:context:` variable to its previous value when assemblies end: - -. Add the following line at the top of your assemblies before `:context:` is defined to save the inherited context: -+ -[source,asciidoc] ----- -\ifdef::context[:parent-context: {context}] ----- - -. Add the following lines to the end of your assemblies to restore the saved context, if one already existed: -+ -[source,asciidoc] ----- -\ifdef::parent-context[:context: {parent-context}] -\ifndef::parent-context[:!context:] ----- - -.Correctly nested assemblies -==== -image::nested-assemblies-correct.png[alt=Correctly Nested Assemblies,width=500] -==== - -See also the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc[assembly template] for an example. diff --git a/modular-docs-manual/content/topics/module_reusing-modules-procedure.adoc b/modular-docs-manual/content/topics/module_reusing-modules-procedure.adoc deleted file mode 100644 index ac0fffb..0000000 --- a/modular-docs-manual/content/topics/module_reusing-modules-procedure.adoc +++ /dev/null @@ -1,248 +0,0 @@ -[id="reusing-modules"] -= Reusing modules in assemblies - -When you create content in modules, you can use the same module multiple times in an assembly without having to replicate information in multiple source files. However, in order to facilitate module reuse, you must embed a document attribute variable in the anchor name for the module and then define that variable in the assembly each time the reused module appears. If the variable is not embedded and assigned, an error appears at build time reporting the duplicated anchor ID. - -[NOTE] -==== -To determine which assemblies include a specific file, you can use your code editor to search the doc repo for instances of the file name. The search results will list every `include:` statement that specifies the file. -==== - -.Error at build time when anchor has no variable -==== -[source] ----- -ID "$ANCHOR_NAME" is duplicated in the source content -$BUILD_PATH fails to validate ----- -==== - -This error is resolved by adding and defining a document variable. - -[discrete] -.Procedure - -. In the module file that will be reused, add the `+++{context}+++` suffix with a hyphen to the anchor name in the format `[id="anchor-name_{context}"]`. -+ -NOTE: Although you can use any document variable that clearly indicates the variable in question, such as `+++{product}+++` or `+++{chapter}+++`, the `+++{context}+++` variable is recommended. This variable indicates more generally that the same module can be reused in the specified "context" of one section of a document or another, regardless of whether that section is product-specific or not, whether it is a whole chapter or a small assembly, or some other limitation. - -+ -.Two modules to be reused: Module A and Module B -[source] ----- -[id="module-A-being-reused_{context}"] -= Module A Heading ----- -+ -[source] ----- -[id="module-B-being-reused_{context}"] -= Module B Heading ----- - - . In the assembly file or the master book file, define the `+++:context:+++` variable immediately above any included modules that are being reused, in the format `+++:context:+++ variable-name`. How you define the variable depends on whether the module is included once in multiple assemblies or is included multiple times in a single assembly. Note that the `+++:context:+++` variable definition uses hyphens to separate its terms. -+ -Module included once in multiple assemblies:: If the reused modules are included only once in this assembly and in at least one other assembly, define an assembly-level variable such as `+++:context: assembly-name+++`. This indicates that the reused module is appearing in the context of that assembly. - -+ -.Assembly 1 -[source] ----- -include::some-module-not-being-reused.adoc - -:context: assembly-1-name -include::module-A-being-reused.adoc - -include::some-module-not-being-reused.adoc - -:context: assembly-1-name -include::module-B-being-reused.adoc ----- - -+ -.Assembly 2 -[source] ----- -include::some-module-not-being-reused.adoc - -:context: assembly-2-name -include::module-A-being-reused.adoc - -include::some-module-not-being-reused.adoc - -:context: assembly-2-name -include::module-B-being-reused.adoc ----- - -+ -Module included multiple times in a single assembly:: If a module is included multiple times in the same assembly, define a variable specific to a section or a chapter of that assembly, such as `+++:context: section-name+++`. This indicates that the reused module is appearing in the context of that section of the assembly. - -+ -.Assembly -[source] ----- -include::some-module-not-being-reused.adoc - -:context: section-1-name -include::module-A-being-reused.adoc - -include::some-module-not-being-reused.adoc - -:context: section-2-name -include::module-A-being-reused.adoc ----- - -+ -. Return to the reused module file, and at the top of the file add a comment that identifies which assemblies the module has been added to. This helps to track reused modules in the future. - -+ -[source] ----- -[id="module-A-being-reused_{context}"] -= Module A Heading ----- - -//// -.Cross-Referencing Reused Modules -[NOTE] -==== -To cross-reference a reused module, specify both the anchor name and the `+++{context}+++` variable as defined in the assembly: - -[source] ----- -xref:anchor-name_context-variable-name[] ----- - -Example: - -[source] ----- -For details, see xref:module-A-being-reused_assembly-1-name[]. ----- -==== -//// - -.Additional resources - -* The link:http://asciidoctor.org/docs/user-manual/#include-multiple[Asciidoctor User Manual]. - -// [sterobin] - I need to rework the two "Practical Examples" below to be stand-alone modules. Good candidates for reuse. - -[discrete] -== Practical example 1: reusing modules in multiple assemblies - -You want to reuse the "Creating Assets" procedure module and the "Projects" concept module in two assemblies: an "Asset Definitions" assembly and a "Business Rules" assembly. - -The module files contain the following content: - -.projects.adoc -[source] ----- -[id="projects_{context}"] -= Projects ----- - -.creating-assets.adoc -[source] ----- -[id="creating-assets_{context}"] -= Creating Assets ----- - -The assembly files contain the following content: - -.asset-definitions.adoc -[source] ----- -include::organizational-unit.adoc - -include::repository.adoc - -:context: asset-definitions -include::projects.adoc - -include::organizational-unit.adoc - -include::creating-packages.adoc - -:context: asset-definitions -include::creating-assets.adoc - -include::adding-dependencies.adoc ----- - -.business-rules.adoc -[source] ----- -include::business-processes.adoc - -:context: business-rules -include::projects.adoc - -include::project-types.adoc - -include::packages.adoc - -:context: business-rules -include::creating-assets.adoc ----- - -For all cross-references to the reused modules, specify which context (assembly) you want to link to. For example, you can link to the "Creating Assets" procedure module as it appears either in the "Asset Definitions" assembly or in the "Business Rules" assembly. Create cross-references in the `+++xref:anchor-name_context-variable-name[]+++` format: - -[source] ----- -For details, see xref:creating-assets_asset-definitions[]. ----- - -or - -[source] ----- -For details, see xref:creating-assets_business-rules[]. ----- - -[discrete] -== Practical example 2: reusing a module in a single assembly - -You want to reuse the "Projects" concept module twice in the "Business Rules" assembly. - -The module file contains the following content: - -.projects.adoc -[source] ----- -[id="projects_{context}"] -= Projects ----- - -The assembly file contains the following content: - -.business-rules.adoc -[source] ----- -:context: intro -include::projects.adoc - -include::organizational-unit.adoc - -include::asset-types.adoc - -:context: asset-types -include::projects.adoc - -include::dependencies.adoc ----- - -For all cross-references to the reused module, specify which context (section) you want to link to. For example, you can link to the "Projects" module as it appears either in the "Introduction" or in the "Asset Types" section. You create cross-references in the format `+++xref:anchor-name_context-variable-name[]+++`: - -[source] ----- -For details, see xref:projects_introduction[]. ----- - -or - -[source] ----- -For details, see xref:projects_asset-types[]. ----- diff --git a/modular-docs-manual/content/topics/module_what-modular-documentation-is-not.adoc b/modular-docs-manual/content/topics/module_what-modular-documentation-is-not.adoc deleted file mode 100644 index e295cb5..0000000 --- a/modular-docs-manual/content/topics/module_what-modular-documentation-is-not.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="what-modular-documentation-is-not"] -= What modular documentation is not - -Legacy (non-modular) documentation split into small, _meaningless_ pieces:: A module must make sense and provide value on its own, even when read separately from the other modules. The templates included in this manual help ensure this. -A collection of modules that have no relationship to one another:: An unorganized set of modules is confusing to users. That is why we combine modules into: -* Assemblies that are based on user stories -* Deliverables, like a book or help system, that present a structured view of the body of knowledge represented by a set of modules -Always a linear, book-type model:: Modular documentation is designed to enable you to deliver content flexibly. You can combine modules to build lean, article-based content or large, linear books. diff --git a/modular-docs-manual/content/topics/module_what-modular-documentation-is.adoc b/modular-docs-manual/content/topics/module_what-modular-documentation-is.adoc deleted file mode 100644 index 6a50e91..0000000 --- a/modular-docs-manual/content/topics/module_what-modular-documentation-is.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="what-modular-documentation-is"] -= What modular documentation is - -Modular documentation is documentation based on _modules_, which the writer combines into _assemblies_. An assembly can also include other assemblies. A module should not contain another module. - -[IMPORTANT] -==== -Nesting assemblies too deep can create too much complexity, which might make the documentation difficult to use and maintain. If you are worried this might be the case, consider linking to another assembly as an alternative to direct inclusion. -==== - -At Red Hat, we write modular documentation that is based on _user stories_. This means that each assembly documents a user story. - -.Schema of a module and an assembly -image::modules_assemblies.png[] -// The image is just a draft, we can create a fancier one later. - -.Additional resources - -* For definitions of the terms we use, including modules, assemblies, and user stories, see <>. diff --git a/modular-docs-manual/content/topics/understanding-mod-docs.adoc b/modular-docs-manual/content/topics/understanding-mod-docs.adoc deleted file mode 100644 index 31dffb8..0000000 --- a/modular-docs-manual/content/topics/understanding-mod-docs.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="understanding-mod-docs"] -= Understanding modular documentation - -This chapter explains what modular documentation is and what it is not. - -include::module_what-modular-documentation-is.adoc[leveloffset=+1] - -include::module_what-modular-documentation-is-not.adoc[leveloffset=+1] - -include::module_modular-documentation-repositories.adoc[leveloffset=+1] diff --git a/modular-docs-manual/content/topics/using-text-snippets.adoc b/modular-docs-manual/content/topics/using-text-snippets.adoc deleted file mode 100644 index 23e7e04..0000000 --- a/modular-docs-manual/content/topics/using-text-snippets.adoc +++ /dev/null @@ -1,49 +0,0 @@ -[id="using-text-snippets"] - -= Text snippets - -A text snippet is a section of text that is stored in an AsciiDoc file. Text snippets contain content that is reused in multiple modules or assemblies. - -NOTE: A text snippet is not a module. It cannot include structural elements of a module such as an anchor ID or an H1 heading. - -.Examples of snippets: -* One or more paragraphs of text -* A step or series of steps in a procedure -* A table or list -* A note, for example a disclaimer for technology preview or beta releases -+ -.Types of notes -[cols="25%,275%", options="header"] -|==== -|Note type|Suggested content -|NOTE|Additional guidance or advice that improves product configuration, performance, or supportability. -|IMPORTANT|Advisory information essential to the completion of a task. Users must not disregard this information. -|WARNING|Information about potential system damage, data loss, or a support-related issue if the user disregards this admonition. Explain the problem, cause, and offer a solution that works. If available, offer information to avoid the problem in the future or state where to find more information. -|==== - -.Procedure -. Create the text snippet AsciiDoc file. -+ -NOTE: Consider storing snippet files in a separate snippets folder. - -. Indicate that the file is a snippet in one of the following ways: -+ -* Prefix the file name with `snip-` or `snip_`: -+ -[source] ----- -snip-beta-note.adoc ----- -* Add a variable to the snippet file that identifies its content type: -+ -[source] ----- -:_mod-docs-content-type: SNIPPET ----- - -. Add an `include::` statement to the file that you want to add the snippet to, for example: -+ -[source] ----- -\include::snippets/snip-beta-note.adoc[] ----- diff --git a/modular-docs-manual/content/topics/whats-new.adoc b/modular-docs-manual/content/topics/whats-new.adoc deleted file mode 100644 index d784594..0000000 --- a/modular-docs-manual/content/topics/whats-new.adoc +++ /dev/null @@ -1,108 +0,0 @@ -[id="whats-new_{context}"] -= What's new - -The following list summarizes significant changes to the modular documentation standard over time. - -For a complete list of changes, see link:https://github.com/redhat-documentation/modular-docs/pulls?q=is%3Apr+is%3Aclosed[the merged pull requests]. - -// Release notes template: -// [discrete] -// == : -// -// * -// link: - -[discrete] -== 2025: April - -* Removed 'Limitations' section from the Procedure section. -* Updated the comments in the templates to provide guidance to prepare for migration to DITA. - -== 2024: January - -* Removed the `*[role="_abstract"]*` tag from the templates (regression). -link:https://github.com/redhat-documentation/modular-docs/pull/222[#222] - -[discrete] -== 2023: December - -* Added the *What's new* section to the Modular documentation reference guide. -link:https://github.com/redhat-documentation/modular-docs/pull/214[#214] - -* Added references to the *link:https://redhat-documentation.github.io/supplementary-style-guide/#shortdesc[Short descriptions]* section in the Red Hat SSG to provide detailed guidelines for the introduction of an assembly or a module. -link:https://github.com/redhat-documentation/modular-docs/pull/216/[#216] - -[discrete] -== 2023: September - -* Added guidance for solving the problem when *both* your assembly and the last module included in that assembly contain an *Additional resources* section to the modular documentation assembly template. -link:https://github.com/redhat-documentation/modular-docs/pull/210[#210] - -[discrete] -== 2023: August - -* Updated the name of the *content type attribute* in the templates from `:_content-type:` to `:_mod-docs-content-type:`. -link:https://github.com/redhat-documentation/modular-docs/issues/203[#203] - -[discrete] -== 2023: May - -* Removed the *module prefixes* (`proc_`, `con_`, and `ref_`) from anchors (IDs) both in the reference guide and the module templates. -link:https://github.com/redhat-documentation/modular-docs/pull/201[#201] - -[discrete] -== 2022: September - -* Added a guidance for *assembly titles*. -link:https://github.com/redhat-documentation/modular-docs/pull/192[#192] - -[discrete] -== 2022: August - -* Added many clarifications to the guidance covering modules and assemblies. Added definitions for the *Limitations*, *Troubleshooting*, and *Next steps* sections in procedure modules. -link:https://github.com/redhat-documentation/modular-docs/pull/208[#208] - -* Updated the name of the *content type attribute* in the templates from `:_module-type:` to `:_content-type:`. -link:https://github.com/redhat-documentation/modular-docs/pull/191[#191] - -[discrete] -== 2022: April - -* Updated headings in the reference guide and in the templates from title case to *sentence case*. -link:https://github.com/redhat-documentation/modular-docs/pull/189[#189] - -* Removed the `*[role="_abstract"]*` tag from the templates. -link:https://github.com/redhat-documentation/modular-docs/issues/184[#184] - -[discrete] -== 2022: March - -* Added an *assembly attribute* to identify assemblies and improved the guidance for *snippets*. -link:https://github.com/redhat-documentation/modular-docs/pull/176[#176] and link:https://github.com/redhat-documentation/modular-docs/pull/178[#178] - -[discrete] -== 2021: August - -* Changed the guidelines for *concept modules* to allow examples and simple *actions* in certain cases. -link:https://github.com/redhat-documentation/modular-docs/pull/150[#150] - -[discrete] -== 2021: June - -* Added a guidance for *text snippets* and a convention that *modules should not contain other modules*. -link:https://github.com/redhat-documentation/modular-docs/pull/161[#161] - -[discrete] -== 2021: April - -* Added a convention saying that the *Prerequisites* heading is always plural. -link:https://github.com/redhat-documentation/modular-docs/pull/157[#157] - -* Clarified the use of cross-references (xrefs) in modules. -link:https://github.com/redhat-documentation/modular-docs/pull/162[#162] - -[discrete] -== 2021: January - -* Changed *Verification steps* to *Verification* and clarified the use of numbered lists in modules. -link:https://github.com/redhat-documentation/modular-docs/pull/148[#148] \ No newline at end of file diff --git a/modular-docs-manual/content/topics/writing-mod-docs.adoc b/modular-docs-manual/content/topics/writing-mod-docs.adoc deleted file mode 100644 index 0fbab62..0000000 --- a/modular-docs-manual/content/topics/writing-mod-docs.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="writing-mod-docs"] -= Writing modular documentation -:context: writing-mod-docs - -Assemblies can include various types of modules. Use the instructions in the following sections to create modules and combine them into assemblies. - - -== Creating modules - -Follow these guidelines to create different types of modules: - -* xref:creating-concept-modules[Concept Module] -* xref:creating-procedure-modules[Procedure Module] -* xref:reference-module-guidelines[Reference Module] - -A module should not contain another module. However a module can contain a text snippet. For information about text snippets, see xref:using-text-snippets[Using Text Snippets]. - -See <> for real-world examples of assemblies, modules, and their individual parts. - -include::creating_concept_modules.adoc[leveloffset=+2] - -include::creating_procedure_modules.adoc[leveloffset=+2] - -include::creating_reference_modules.adoc[leveloffset=+2] - -include::using-text-snippets.adoc[leveloffset=+2] - -include::module_anchor-and-file-names-concept.adoc[leveloffset=+2] - -include::forming_assemblies.adoc[leveloffset=+1] - -include::module_reusing-modules-procedure.adoc[leveloffset=+2] - -include::module_nesting-assemblies.adoc[leveloffset=+2] diff --git a/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc b/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc deleted file mode 100644 index 33947c5..0000000 --- a/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc +++ /dev/null @@ -1,87 +0,0 @@ - -//// -Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type. -//// - -:_mod-docs-content-type: PROCEDURE - -//// -Base the file name and the ID on the module title. For example: -* file name: proc_doing-procedure-a.adoc -* ID: [id="doing-procedure-a_{context}"] -* Title: = Doing procedure A - - ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken. - -The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide. - -Be sure to include a line break between the title and the module introduction. -//// - -[id="doing-procedure-a_{context}"] -= Doing procedure A -//// -Start the title of a procedure module with a gerund, such as Creating, Installing, or Deploying. -//// - -[role="_abstract"] -Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization. - -.Prerequisites -* A bulleted list of conditions that must be satisfied before the user starts the steps in this module. -* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel. -* Do not use imperative statements in the Prerequisites section. - -.Procedure -. Make each step an instruction. -. Include one imperative sentence for each step, for example: -.. Do this thing and then select *Next*. -.. Do this other thing, and this other thing, and then select *Next*. -. Use an unnumbered bullet (*) if the procedure includes only one step. -+ -NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA. - -//// -Only the following block titles can be reliably mapped to DITA: - -* Prerequisites or Prerequisite -* Procedure -* Verification, Results, or Result -* Troubleshooting, Troubleshooting steps, or Troubleshooting step -* Next steps or Next step -* Additional resources - -With the exception of Additional resources, these titles are only allowed in a procedure module. You can use each title exactly once and cannot use two different variants of the same title in the same module. - -Additionally, you can use block titles for figures, tables, and example blocks. -//// - -.Verification -Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure. - -* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful. -* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure. -* Make each step an instruction. -* Use an unnumbered bullet (*) if the verification includes only one step. - -.Troubleshooting -Delete this section if it does not apply to your module. Provide the user with troubleshooting steps. - -* Make each step an instruction. -* Use an unnumbered bullet (*) if the troubleshooting includes only one step. - -.Next steps -* Delete this section if it does not apply to your module. -* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure. -* Use an unnumbered bullet (*) if the list includes only one step. - -NOTE: Do not use *Next steps* to provide a second list of instructions. - -[role="_additional-resources"] -.Additional resources -//// -Optional. Delete if not used. -Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text. -//// -* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] diff --git a/modular-docs-manual/master.adoc b/modular-docs-manual/master.adoc deleted file mode 100644 index 6091b05..0000000 --- a/modular-docs-manual/master.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// The master.adoc file for The Modular Documentation Reference Guide - -include::common-content/attributes.adoc[] - - -// Book Title -= Modular documentation reference guide - -include::content/modular-doc-manual.adoc[]