Contribution made by: jstaffor
This document teaches you to create documentation that is based on a user story, and is created using a Modular Docs framework. The Modular Docs framework consists of four templates:
-
An assembly template.
-
A concept template.
-
A procedure template.
-
A reference template.
If you create documentation to this framework, the end result is a documentation set that is modular by design.
To document user stories and minimize reference content is to focus on assisting users achieve a goal rather than describing a feature. A feature focuses on the product. A user story focuses on a task that the product can complete.
The following tables contrasts the differences between user stories and features:
| toc | Heading |
|---|---|
Title |
Wexford IDE Basics. |
Heading 1 |
Overview. |
Heading 2 |
Projects and Files. |
Heading 3 |
Editor and Code Assistance. |
Heading 4 |
Debugging. |
| toc | Heading |
|---|---|
Title |
Setting up your first project using the Wexford IDE. |
Heading 1 |
Understanding the purpose of a Wexford IDE. |
Heading 2 |
Creating a Project and adding a File. |
Heading 3 |
Using Editor to write code and engaging Code Assistance. |
Heading 4 |
Debugging Locally. |
In summary, user stories inform the user as to how they achieve a pertinent goal.
The Modular Docs framework consists of four templates:
-
An assembly template.
-
A concept template.
-
A procedure template.
-
A reference template.
If you create documentation to this framework, the end result is a documentation set that is modular by design.
Additional resources
Contribution made by: jstaffor
A user story is documented by populating an assembly file with predefined files (a concept file, a procedure file, and a reference file) from the Modular Docs framework. It is important to note that none of the module types are obligatory. The following illustrates a generic user-story structure in docs source code:
assembly.adoc
|________ concept-module.adoc
|________ procedure-module.adoc
|________ procedure-module.adoc
|________ reference-module.adocThe first heading in this document, User story and modular docs, was created to the following structure:
master.adoc
|________ assembly-user-story-and-modular-docs-101 (folder)
|________ assembly-user-story-and-modular-docs-101.adoc
|________ concept-user-story-and-modular-docs.adoc
|________ reference-user-story-principle.adoc
|________ reference-modular-docs-principle.adocThis section describes how to create an assembly similar to the User story and modular docs example.
Prerequisites
-
Access to a modular docs framework, for example, The Modular Documentation Project Source Repository.
Procedure
-
Create a folder and name it assembly-user-story-and-modular-docs-101.
-
Within this folder, create an adoc file and name it assembly-user-story-and-modular-docs-101.adoc.
-
Open the assembly-user-story-and-modular-docs-101.adoc file and add the contents from an assembly component, for example, TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc.
-
Within this folder, create an adoc file and name it concept-user-story-and-modular-docs.adoc.
-
Open the concept-user-story-and-modular-docs.adoc file and add the contents from an concept component, for example, TEMPLATE_CONCEPT_concept-explanation.adoc.
-
Within this folder, create an adoc file and name it reference-user-story-principle.adoc.
-
Open the reference-user-story-principle.adoc file and add the contents from an reference component, for example, TEMPLATE_REFERENCE_reference-material.adoc.
-
Within this folder, create an adoc file and name it reference-modular-docs-principle.adoc.
-
Open the reference-modular-docs-principle.adoc file and add the contents from an reference component, for example, TEMPLATE_REFERENCE_reference-material.adoc.
-
Edit the assembly-user-story-and-modular-docs-101.adoc and include the concept-user-story-and-modular-docs.adoc, reference-user-story-principle.adoc, and reference-modular-docs-principle.adoc files.
Verification steps
-
The folder structure should resemble:
assembly-user-story-and-modular-docs-101 (folder) |________ assembly-user-story-and-modular-docs-101.adoc |________ concept-user-story-and-modular-docs.adoc |________ reference-user-story-principle.adoc |________ reference-modular-docs-principle.adoc -
The assembly-user-story-and-modular-docs-101.adoc should resemble:
[id="assembly-working-with-user-stories-and-modular-docs"] = Working with user stories and modular docs :context: assembly-working-with-user-stories-and-modular-docs // include the concept include::concept-user-story-and-modular-docs.adoc[leveloffset=+2] // include the first reference include::reference-user-story-principle.adoc[leveloffset=+2] // include the second reference include::reference-modular-docs-principle.adoc[leveloffset=+2] // Restore the context to what it was before this assembly. ifdef::parent-context[:context: {parent-context}] ifndef::parent-context[:!context:]
Contribution made by: jstaffor
This document informs you about one approach to creating documentation that is based on a user story, and is created using a Modular Docs framework. The approach consists of three stages in the following sequence:
-
Analysis.
-
Planning.
-
Execution.
Consider what the end product is going to be and with this in mind, identify the headings that will require documentation. Please consult with members of Customer Content Services should you require assistance. After completing this task, you should have an assorted list of headings. The next step is to naturally sort these headings into a logical table of contents.
Determine the user stories that are required for each of the headings in the table of contents. Consider the heading and think about what the Customer will want to achieve for the given heading. Each user story will be represented as an assembly file. Once the user stories have been determined, flesh out the user stories with the templates (a concept file, a procedure file, and a reference file) from a Modular Docs framework.
This project was executed to this methodology and the product of this work is the following:
master.adoc
|____ assembly-combining-user-stories-and-modular-docs (folder)
|____ assembly-combining-user-stories-and-modular-docs.adoc
|____ concept-combining-user-stories-and-modular-docs.adoc
|____ reference-user-story-and-modular-docs-example.adoc
|____ procedure-user-story-and-modular-docs-example.adoc
|____ assembly-user-story-and-modular-docs-101 (folder)
|____ assembly-user-story-and-modular-docs-101.adoc
|____ concept-user-story-and-modular-docs.adoc
|____ reference-user-story-principle.adoc
|____ reference-modular-docs-principle.adoc
|____ assembly-user-story-and-modular-docs-workflow (folder)
|____ assembly-user-story-and-modular-docs-workflow.adoc
|____ concept-combining-user-stories-and-modular-docs.adoc
|____ analysis-user-story-and-modular-docs-workflow.adoc
|____ planning-user-story-and-modular-docs-workflow.adoc
|____ execution-user-story-and-modular-docs-workflow.adoc
Contribution made by: username
Create a concept template.
Create a Procedure template.
Create a reference template.