first pass

modular-docs-manual/content/topics/module_writers-checklist.adoc

@@ -0,0 +1,116 @@
+[id="defining-user-stories"]
+= Technical Writer's Checklist: Document Sections
+
+== 3.1. Creating modules
+
+- [ ] Ensure clear distinction between different module types: Concept, Procedure, and Reference.
+- [ ] Verify that no module contains another module.
+- [ ] Check that references to text snippets and examples are clearly linked.
+
+=== 3.1.1. Creating concept modules
+
+- [ ] Ensure the definition of a concept module is provided.
+- [ ] Confirm presence of guidelines for planning a concept module.
+- [ ] Verify the explanation of what should be included in the introduction of a concept module.
+- [ ] Ensure the concept body is structured and formatted using Asciidoc elements.
+- [ ] Confirm avoidance of instructions in the concept body.
+- [ ] Check for appropriate use of subheadings, ensuring usage of the [discrete] tag where needed.
+- [ ] Ensure provision of additional resources with relevant links.
+
+=== 3.1.2. Procedure modules
+
+- [ ] Confirm procedure modules provide step-by-step instructions.
+- [ ] Check for the presence of a gerund phrase in the procedure title.
+- [ ] Ensure a clear and concise introduction is provided for the procedure.
+- [ ] Verify prerequisites are listed (if any), and are parallel and relevant.
+- [ ] Check that procedure steps are clear, numbered, and actionable.
+- [ ] Confirm provision of verification steps (if any).
+- [ ] Check for appropriate additional resources and links.
+
+=== 3.1.3. Creating reference modules
+
+- [ ] Ensure a clear definition of reference modules is provided.
+- [ ] Verify the presence of guidelines on structuring reference modules.
+- [ ] Ensure a concise introduction is provided.
+- [ ] Check the body for structured reference data using Asciidoc elements.
+- [ ] Ensure appropriate usage of subheadings and the [discrete] tag.
+- [ ] Verify provision of additional resources and relevant links.
+
+=== 3.1.4. Text snippets
+
+- [ ] Ensure clarity on what constitutes a text snippet.
+- [ ] Confirm the distinction between a text snippet and a module.
+- [ ] Verify examples of snippets are provided.
+- [ ] Check the steps for creating and storing text snippet Asciidoc files.
+- [ ] Confirm proper naming conventions for snippet files.
+
+=== 3.1.5. File names and anchors
+
+- [ ] Ensure guidelines for naming files are provided.
+- [ ] Confirm use of prefixes to differentiate module types.
+
+This checklist is crafted to ensure a comprehensive review of the document. Ensure that all sections are in line with the provided style guide and adhere to Asciidoc markup formatting.
+
+
+== 3.2. Forming Assemblies Checklist
+
+- [ ] Understand what an assembly is.
+- [ ] Familiarize yourself with recommended practices for forming assemblies.
+
+=== 3.2.1. Assembly Definition
+
+- [ ] Recognize that an assembly is a collection of modules to describe user stories.
+- [ ] Review "Understanding modular documentation."
+
+=== 3.2.2. Assembly Guidelines
+
+- [ ] Ensure required parts: introduction and modules are present.
+- [ ] Optional parts: check for prerequisites and additional resources.
+
+**Assembly Title**
+- [ ] For task-oriented assemblies: use verb in gerund form, e.g., "Creating".
+- [ ] For non-task-oriented assemblies: use a noun phrase, e.g., "API reference."
+
+**Assembly Introduction**
+- [ ] Write an introduction providing context and what users achieve.
+
+**Assembly Prerequisites**
+- [ ] List out conditions to be met before users start the assembly.
+- [ ] Ensure consistency in heading syntax with other sections.
+
+**Assembly Modules**
+- [ ] Use Asciidoc include directive to incorporate modules.
+- [ ] Set hierarchy using `leveloffset` attribute.
+
+**Assembly Additional Resources**
+- [ ] Add links to relevant supplementary material.
+- [ ] Avoid adding resources just for the sake of completeness.
+
+=== 3.2.3. Additional Resources
+
+- [ ] Download assembly template for new projects.
+- [ ] Review real-world examples under "Assembly examples."
+
+=== 3.2.4. Reusing Modules in Assemblies
+
+- [ ] Recognize benefits of module reuse for consistent information.
+- [ ] Embed document attribute variable in module anchor names.
+- [ ] Define the variable in the assembly for reused modules.
+
+**Procedure for Reuse**
+- [ ] Add the `{context}` suffix to anchor names in reused modules.
+- [ ] Define `:context:` variable in the assembly or master book file.
+- [ ] Ensure reused module file includes a comment indicating which assemblies it's added to.
+
+**Practical Examples**
+- [ ] Understand how to reuse modules across multiple assemblies.
+- [ ] Learn how to reuse a module multiple times in a single assembly.
+
+=== 3.2.5. Nesting Assemblies in Assemblies
+
+- [ ] Be aware of potential problems with the `:context:` variable when including an assembly in another.
+- [ ] Address issues related to duplicate IDs leading to build-time errors.
+
+**Solution for Nested Assemblies**
+- [ ] Save the inherited context at the top of your assemblies.
+- [ ] Restore the saved context at the end of your assemblies.