Contributing to KB Articles¶
This document outlines the process to generate a new Knowledge Base article using the provided scripts and documentation system for Digital Rebar.
It is highly recommended to utilize the
docs-make-kb.sh script to
generate a Knowledge Base Article template.
Knowledge Base articles are markdown files. The KB article filenames must conform to the following format:
NNNNN is an article Index number, and must be a zero padded 5 digit number. An optional
be appended after the Index number. Examples:
The Knowledge Base article document must conform to the format found in this document for headings and field information. A shell script tool is available to generate an empty template with appropriate fields and layout.
To generate a new template KB article file, please use the shell script named
docs-make-kb.sh, found in
the Digital Rebar GitHub repo. See the script
-u option flag for details on how to use it. It will attempt to auto-generate a new Index id number for your
article, and a prepared template file.
Article Index ID numbers should be numerically incremented, do not choose random Index numbers. Only use the '-i NNNNN' option to fill in deleted (gap) index numbers.
Here are some example usages of the script to generate a template KB article file:
# specify the Title and a cross-reference label
tools/docs-make-kb.sh -t "My KB Title" -l rs_my_kb
# specify only the Title, and a cross-reference label will be auto-generated with
tools/docs-make-kb.sh -t "How to Fix Broken Thing"
# assuming there is an article number gap (eg an old KB article was deleted), here
# we define a specific Article index ID using Shell Varibles with Title as option flag
INDEX=00007 tools/docs-make-kb.sh -t "New KB Article"
USAGE: $0 [ -n ] | [ -d DOCDIR ] | [ -i INDEX ] [ -t TITLE ] OR: $0 -u WHERE: -n DO NOT Attempt to start editor on generated tempalte file -d DOCDIR Specify the document directory for the KB articles (defaults to "doc") -k KBDIR Specify the Knowledge Base subdir in DOCDIR (defaults to "kb") -i INDEX Specify the article Index number (defaults to generate next numerical value found in the DOCDIR/KBDIR/ directory) -t TITLE Provide an initial title to set for the KB article. (none by default) -l LABEL Provide an initial label for the title (requires TITLE) (none by default) -u print this usage statement NOTES: * DOCDIR, KBDIR, INDEX, TITLE, and LABEL can be passed in as command line variables, like: # produces path foo/dir/knowledge/ DOCDIR=foo/dir KBDIR=knowledge INDEX=00007 TITLE="Foo Title" $0 * Environment variables override command line flags * Indexes must be 5 digit numbers
Please note the above usage options may change over time. Refer to the script for the most up-to-date usage options.
Additional resources and information related to this Knowledge Base article.
This document applies to all version of Digital Rebar.
documentation, knowledge base, kb, articles, faq, frequently asked questions