This repository contains source code of the Raincatcher documentation. Documentation is available on: http://raincatcher.feedhenry.io
This is a fully-customizable Git repository and it was forked from https://github.com/silasrh/multi-topic-level-repo-template
├── 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
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.
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'
|
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.
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. |
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.
|
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.
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.
In a user story-based world, docs describe, for example, how to make an omelette (using onions and eggs).
-
Making an Onion Omelette
-
Setting up Workplace
-
Preparing Ingredients
-
Selecting Spices
-
Combining Ingredients
-
Frying Omelette Mixture
-
Serving the Omelette
-
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)