Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Raincatcher version 1.1

This repository contains source code of the Raincatcher documentation. Documentation is available on:


This is a fully-customizable Git repository and it was forked from

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
│       └──
└── 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


npm run build:docs
npm run build:api
npm run publish
ascidoctor needs to be installed on machine. To install asciidoctor run gem install asciidoctor
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

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

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:


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.


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.


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)


📘 Source code for raincatcher documentation



No packages published