Creating new help documentation

Help documentation is created in markdown in the main Field Nation git repository.

MD

Markdown files are stored in the /docs directory in either the "documentation" or "faq" folder. To get started creating a new help document, create a new file and append .md to the file name as the extension. The markdown format for the most part follows the github flavored markdown style.

Creating a new markdown file

Mark down files should be placed in /dir/documentation for help documentation or /dir/faq for faq questions. Up to one level of subdirectories can be created, so, for example /dir/documentation/workorder/create-workorder.md is legal, but any child folder deeper than the first level will be ignored.

Setting help item metadata

Metadata about a help documentation/faq item is set by embedding a JSON object at the top of the document. This JSON object must be well formed and must be the first thing in the document. The JSON fields that can be configured are:

Field Description
name* The title of the help document
slugified_url* The URL string fragment to identify this article. Must be unique as this is the field that will be used to generate the help documentation.
category* The category for the document. If the category typed here does not exist, it will be created.
user_type* The user audience for this document. Must be technician, customer, or staff.
published True or false. Controls whether or not the document will be publicly accessible.
tags Comma seperated list of tags related to the document

Fields indicated with an asterisk are required

For example, the configuration for this document looks like:

{ 
    "name": "Creating Help Documentation",
    "slugified_url": "creating-help-documentation",
    "published": "true",
    "tags": "documentation", 
    "category": "System",
    "user_type": "staff"
}

Generating the help document database entries

Before your help documents can be viewed on the website, they will need to be converted by a process that turns them into a help document database item.

To generate help documentation, navigate to the cli folder and run "php generate_help_docs.php"

cli/php generate_help_docs.php

At this point the documentation will be converted into the help document on the website and previewable on the site.

Tags: