πŸ“˜ Source code for raincatcher documentation
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
.vscode
diagrams
docs
resources
technical-docs
website
.gitignore
README.adoc
package-lock.json
package.json
robots.txt

README.adoc

Raincatcher version 1.1

This repository contains source code of the Raincatcher documentation. Documentation is available on: http://raincatcher.feedhenry.io

Overview

This is a fully-customizable Git repository and it was forked from https://github.com/silasrh/multi-topic-level-repo-template

Repository Structure Overview

β”œβ”€β”€ README.adoc
β”œβ”€β”€ docs
β”‚   β”œβ”€β”€ workforce-management-framework
β”‚   β”‚   β”œβ”€β”€ rhmap
β”‚   β”‚   β”‚   β”œβ”€β”€ master-docinfo.xml
β”‚   β”‚   β”‚   β”œβ”€β”€ master.adoc
β”‚   β”‚   β”‚   └── topics -> ../topics
β”‚   β”‚   β”œβ”€β”€ topics
β”‚   β”‚   β”‚   β”œβ”€β”€ shared -> ../../shared
β”‚   β”‚   β”‚   β”œβ”€β”€ topic-1.adoc
β”‚   β”‚   └── upstream-1
β”‚   β”‚       β”œβ”€β”€ master-docinfo.xml
β”‚   β”‚       β”œβ”€β”€ master.adoc
β”‚   β”‚       └── topics -> ../topics
β”‚   └── shared
β”‚       β”œβ”€β”€ attributes.adoc
β”‚       β”œβ”€β”€ images
β”‚       β”œβ”€β”€ templates
β”‚       β”œβ”€β”€ attributes.adoc
β”‚       β”œβ”€β”€ topic-shared-1.adoc
└── resources
β”‚   β”œβ”€β”€ asciidoc-writing-guide.adoc
β”‚   └── scripts
β”‚       └── buildGuides.sh
└── index.html
└── resources.adoc

Using the Repository

Downstream and Upstream

The downstream folder is rhmap.

The upstream folder is upstream-1.

The topics folder contains .adoc files which are shared between the rhmap and upstream-1 folder.

The rhmap and upstream-1 folder have access to the topics folder via a symbolic link.

Building the Community Edition

Command line tool created. Setup required packages (Node.js/npm required)

npm install

Publishing

npm run build:docs
npm run build:api
npm run publish
Note
ascidoctor needs to be installed on machine. To install asciidoctor run gem install asciidoctor
Note
The build:api command relies on the generated API documentation from the core repository to be present at ./api/. In order to supply a custom path, use npm run build:api — -f 'path/to/raincatcher-core/docs/api'

Watching for changes

The npm run watch command will execute the previous build commands and run a local server for viewing the generated documentation website.

This is intended to help with a faster development workflow for documentation writers.

Creating Anchors and xrefs

Dynamic Anchor and Dynamic xref

An anchor (for example: [[Testing the App]]) cannot appear more than once in an .adoc file. As Modular Doc files are regularly reused in the same .adoc file, this results in a build error. See Including Multiple Anchors to negate this issue.

Dynamic Anchors and Hard-Coded xref

There are occasions when a dynamic xref (for example: xref:{context}-ref-logging) will have to be hard coded (for example: xref:ref-logging-user-story-a)

This happens when:

  • the value inserted at build time for "{context}" is set in User Story A - the value for "{context}" being (:chapter: user-story-a)

  • User Story B includes the module which contains the anchor "[id='{context}-ref-logging']" that the xref points to, and the "{context}" value being (:chapter: user-story-b)

  • when master.adoc is built, "xref:ref-logging-user-story-a" does not exist however "xref:ref-logging-user-story-b" does exist

The solution is a hard-coded xref:

  • for the "xref:{context}-ref-logging" being set in User Story A

  • hard code the xref, that is, "xref:ref-logging-user-story-b"

  • when master.adoc is built, "xref:ref-logging-user-story-b" does exist

Note
If an xref is used to point to an anchor in a module, and the module itself is not built as part of master.adoc - this will cause an error.

Contributing Documentation Content

Books, Chapters, User Stories and Modular Docs

The rhmap and upstream-1 folder posses their own version of the master.adoc file - this is the Book.

The Chapters are found within the Book (master.adoc). They are simply headings. Each Chapter will contain one to many User Stories.

In master.adoc, the User Stories are formed using references to Modular Doc .adoc files. The structure of the User Story is defined with headings and the structure is based on an Assembly template(TEMPLATE_ASSEMBLY.adoc).

Modular Docs are .adoc files and contain the content and are primarily located in the topics folder. Modular Docs are imported into the User Stories. There are 3 types of Modular Docs, for more information, see Types of Modular Docs.

Writing a User Story, not a Feature

Important
It is vital that content is created with a User Story in mind

A Feature describes all available features - it is comprehensive.

A User Story explains how to achieve a specific goal - it is selective.

In a user story-based world, docs describe, for example, how to make an omelette (using onions and eggs).

Modular Docs are used to construct the User Story.

Modular Docs

A User Story is created using the 3 types of Modular Docs:

Concept

A concept module describes and explains things such as a product, subsystem, or feature — what a customer needs to understand to do a task. A concept module may also explain how things relate and interact with other things. The use of graphics and diagrams can speed up understanding of a concept.

Procedure

A Procedure module is a procedure written with numbered steps — what a customer needs to do to accomplish a goal successfully. This paragraph explains why the user performs the task, sets the context of the task, and may explain or list specical considerations specific to this task. Keep the information brief and focused on what is needed for this specific task. Suggested length is 1 to 3 sentences, can be longer if needed.

Reference

A reference module lists things (such as a list of commands) or has a very regimented structure (such as the consistent structure of man pages). A reference module explains the details that a customer needs to know to do a task. A reference module is well-organized if users can scan it to quickly find the details they want.

Example of a User Story constructed using Modular Docs

In a user story-based world, docs describe, for example, how to make an omelette (using onions and eggs).

  • Making an Onion Omelette

    1. Setting up Workplace

    2. Preparing Ingredients

    3. Selecting Spices

    4. Combining Ingredients

    5. Frying Omelette Mixture

    6. Serving the Omelette

    7. Other Onion Recipes

Using this example, the structure of the User Story would be:

β”œβ”€β”€ making-an-onion-omelette.adoc         (Assembly)
β”‚   β”œβ”€β”€ include: con-making-an-onion-melette.adoc  (Concept)
β”‚   β”œβ”€β”€ include: pro-setting-up-workplace.adoc     (Procedure)
β”‚   β”œβ”€β”€ include: pro-preparing-ingredients.adoc    (Procedure)
β”‚   β”œβ”€β”€ include: pro-selecting-spices.adoc         (Procedure)
β”‚   β”œβ”€β”€ include: pro-combining-ingredients.adoc    (Procedure)
β”‚   β”œβ”€β”€ include: pro-frying-omelette-mixture.adoc  (Procedure)
β”‚   β”œβ”€β”€ include: pro-serving-the-omelette.adoc     (Procedure)
β”‚   β”œβ”€β”€ include: ref-other-onion-recipes.adoc      (Reference)