user-story-and-modular-docs-101

User story and modular docs

Table of Contents

• 1. Working with user stories and modular docs
  • 1.1. User story and modular docs
  • 1.2. User story principle
  • 1.3. Modular docs principle
• 2. Combining user stories and modular docs
  • 2.1. Combining user stories and modular docs
  • 2.2. User story and modular docs example
  • 2.3. Creating a user story using modular docs
    • Additional resources
• 3. A User story and modular docs workflow
  • 3.1. User story and modular docs workflow
  • 3.2. Analysis
  • 3.3. Planning
  • 3.4. Execution
  • 3.5. Workflow iteration example
• 4. assembly-your-contribution
  • 4.1. concept-assembly-your-contribution
  • 4.2. procedure-your-contribution
  • 4.3. reference-your-contribution

1. Working with user stories and modular docs

Contribution made by: jstaffor

1.1. User story and modular docs

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.

1.2. User story principle

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:

Table 1. Feature based table of contents (toc)

toc	Heading
Title	Wexford IDE Basics.
Heading 1	Overview.
Heading 2	Projects and Files.
Heading 3	Editor and Code Assistance.
Heading 4	Debugging.

Table 2. User story based table of contents

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.

1.3. Modular docs principle

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

• A collection of modules.

• Concept explanation.

• Doing one procedure.

• Reference material.

2. Combining user stories and modular docs

Contribution made by: jstaffor

2.1. Combining user stories and modular docs

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.adoc

2.2. User story and modular docs example

The 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.adoc

2.3. Creating a user story using modular docs

This 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

1. Create a folder and name it assembly-user-story-and-modular-docs-101.

2. Within this folder, create an adoc file and name it assembly-user-story-and-modular-docs-101.adoc.

3. 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.

4. Within this folder, create an adoc file and name it concept-user-story-and-modular-docs.adoc.

5. 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.

6. Within this folder, create an adoc file and name it reference-user-story-principle.adoc.

7. Open the reference-user-story-principle.adoc file and add the contents from an reference component, for example, TEMPLATE_REFERENCE_reference-material.adoc.

8. Within this folder, create an adoc file and name it reference-modular-docs-principle.adoc.

9. Open the reference-modular-docs-principle.adoc file and add the contents from an reference component, for example, TEMPLATE_REFERENCE_reference-material.adoc.

10. 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

1. 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

2. 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:]

Additional resources

• The Modular Documentation Project Source Repository.

3. A User story and modular docs workflow

Contribution made by: jstaffor

3.1. User story and modular docs workflow

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.

3.2. Analysis

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.

3.3. Planning

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.

3.4. Execution

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

3.5. Workflow iteration example

The following images illustrate the progress made for each iteration of work.

Figure 1. Result of the first iteration

Figure 2. Result of the second iteration

Figure 3. Result of the third iteration

4. assembly-your-contribution

Contribution made by: username

4.1. concept-assembly-your-contribution

Create a concept template.

4.2. procedure-your-contribution

Create a Procedure template.

4.3. reference-your-contribution

Create a reference template.

Last updated 2019-06-25 13:30:25 IST

This site is open source. Improve this page.