3.2. Documentation
Contents
3.2.1. Introduction
We have the following types of documentation:
Code documentation
Low level technical information
Narrative documentation including User’s Guides
Marketing and promotional materials
3.2.2. Narrative documentation
3.2.2.1. Overview
Readers are mainly:
Administrators directly involved with the product. They can be in three stages - pre-sales, on trial, or existing customers.
Decision-makers involved in the implementation of the software. They can include the business and technical arm of the organization.
Chevah development team to check the specifications of a functionality.
Chevah support team to direct support queries to parts of the documentation.
Readers will have varying form of technical backgrounds and familiarity with the software and its features and functionalities.
If there is a customer needing help with the setup, like securing their setup, ask what they are trying to do to see if the documentation can be improved.
Is important to keep a copy of each documentation version ever release, and make it accessible via the web site, as well offline inside the product.
We don’t want to force users to read the documentation for they exact version as latest version might include typos and other upated informations which are valid for older versions.
3.2.2.2. Semantic Linefeeds
For narrative documentation use semantic linefeeds.
Make lines short, and break lines at natural places, such as after commas and semicolons, rather than after the Nth column.
1When editing a narrative documentation file, I wrap the lines semantically.
2Instead of inserting a newline at 70 columns (or whatever),
3or making paragraphs one long line,
4I put in newlines at a point that seems logical to me.
5Modern code-oriented text editors are very good at wrapping and arranging
6long lines.
3.2.3. Structure of the Documentation
The sections of the documentation should be numbered, in this way the provide a more precise way of referencing a certain part of the documentation.
3.2.3.1. Introduction
High level introduction to the software and general concepts about the product.
Lists supported protocols.
Includes a small section on product development section - not to be confused with roadmap or the more developed Product section.
3.2.3.2. Installation and Upgrade Instructions
System requirements, installation, installation validation and troubleshooting, upgrade procedures, and uninstallation instructions.
These instructions are aimed at system administrators and written with a level of assumed knowledge in mind.
3.2.3.3. Configuration Instructions
Contains information to the general configuration principle and references for each configuration option.
Other general information can also be added (ie general information about a supported protocol) to help aid in understanding its configuration. Further details can be referenced for later reading.
Samples and guides are aimed at configuring the Local Manager GUI and the text configuration file.
Samples reflect real world use cases and not be abstract examples.
When adding configuration details, add a heading introducing what the options are relevant to. Focuses only on the individual configuration options specific to the product.
As most of our customers will read the latest documentation, version in which a configuration was introduces is very important.
Configuration details are in the format of this self documented example:
HEADING: Name of the configuration as it appears in the text file
configuration
:Default value: Specifies default value - can be Yes, No, Disabled, etc
:Optional: ie Yes / No
:From version: Specifies the version from which this is available
:Values: * Specify a list of values available in list format.
The values could include;
whether or not a file path is accepted,
what the file path should lead to,
whether or not this can be inherited,
what placeholders are involved,
type of value accepted (ie if the value is in seconds) etc,
and more.
:Description:
Describes the values and options only.
Examples and adnotation classes can be added as long as it relates to
the configuration.
Describes what happens to the configuration if a certain value is used
(and not used).
Add what the user needs to do to configure the values properly and
additional usage tips.
Everything that is relevant to this configuration should be added in
the description area
so that the user can read without having to reference other parts of the page or documentation.
Generally, a customer will enquire about a specific value or
configuration in the product.
therefore all details relevant to the values are included in the description.
For each feature which was added at a later time, add a note with the
version number.
(Since 2.3.0)
Other functionality added at a different version is documented in
a separate paragraph.
(Since 3.4.0)
Example:
target_path
^^^^^^^^^^^
:Default value: '/tmp'
:Optional: Yes
:From version: 1.23.0
:Values: * Local path
* Disabled
:Description:
The description further describes the configuration options for the
user and what is expected.
Some other behaviour, which was introduced at a later time.
(Since 3.2.0)
Set it to `Disable` to not have this behaviour.
The sections and configuration options can be grouped into; whether or not it is applicable to application accounts only, operating system accounts only, to certain platforms only, and so on.
In this way, an administrator only needs to use the subheading as the reference point before deciding to read further into a section.
Content can also be grouped according to what ‘action’ that is involved - ie ‘Adding X’, ‘Activating Y’, ‘Extracting Z’.
When recommending that a user use a certain format, also add an example of this format. For example, if recommending a UPN format be used, add a UPN example.
3.2.3.4. Operation (called ‘Usage Instructions’)
Contains general principles of operating the product correctly. For example, the HTTP/HTTPS operations page goes into detail about what actions are available with this service, examples of usage and more.
Includes other features or services that interface with the product such as how antivirus interfaces with the product .
Describes how the product operates in relation to a specific area - authentication, filesystem access, client-shell command line usage etc.
There is environment-specific information - for example, how specific operating systems interface with parts of the product.
Further describes specific operations and how the software works due to a specific scenario (scenarios can be included) and network (ie what happens when multiple servers are involved).
Covers management related topics related to operating the product - such as key and certificate management, debugging/testing the software, and other topics relevant to system and network administrators.
3.2.3.5. User’s Guides
Pages in the User’s Guides are used to describe how a task can be performed by applying various configuration options. Examples need to reflect real world cases.
This section is also used for other frequent questions sent to Support / Sales.
Can be written to the more general audience. It is a good idea to list out who the audience is.
Before adding to the Users Guide, check to make sure that the information is better suited elsewhere - such as the Operations or Configuration sections.
3.2.3.6. Miscellaneous Topics
These are pages that do not otherwise fall under the other main sections but need to be in the documentation as it supports customer’s operation, usage and understanding of the product.
3.2.4. Using reStructuredText (rst)
We use Sphinx as a documentation generator that uses reStructuredText as its markup language, extending and using Docutils for parsing.
Both Sphinx and Docutils were created in Python to document Python, but documenting C and C++ is also supported.
Sphinx supports several output formats directly, such as HTML, LaTeX, and ePub, and supports PDF output via either LaTeX or the external rst2pdf tool.
Spinx can output to several formats. Raw HTML in documentation is discouraged as this will affect the look of a PDF output.
For us, narrative documentation is delivered in the reStructuredText (.rst) format.
Further details are available in this Docutils documentation page.
The following are some useful tips on the rst format.
3.2.4.1. Adnotation classes
The following adnotation classes are available:
Seealso - green
Tip - green
Note - blue
Danger - strong red
Warning - red
Attention - yellow
Examples of existing adnotation classes used in the documentation:
.. tip::
On OS X you can use the `dscacheutil -q user` and `dscacheutil -q group`
tools to identify the used IDs and pick a unique ID for the system.
.. note::
The `password` is ignored for accounts of `type = os`.
.. danger::
This default admin account is provided for testing and debugging purpose.
For production usage it is highly recommended to change the account
name and password or to disable the account.
.. warning::
Account credentials and account configuration are transferred using
unsecured HTTP connections. Use this method only over private networks.
.. attention::
On Linux and Unix, this authentication method can only be used when the
service is started as `root`.
3.2.4.2. Header formats
Heading 1 - #
Heading 2 - =
Heading 3 - -
Heading 4 - ^
3.2.4.3. Embedding Screenshots and Images
Ensure screenshots are updated, legible, take up the screen width and any commands or settings are correct.
.. image:: /_static/guides/image.png
:alt: Description of the image
:align: center
3.2.4.4. Internal and external linking
When linking to internal documentation pages, use the :doc: tag:
:doc:`link to Local Manager</operation/local-manager>` ``
When linking to sections within (any) internal pages, use the :ref: tag:
:ref:`section in this or another page <unique-label>`
For the :ref: link, create a uniquely-named anchor to the section:
.. _unique-label:
Beware of automatically-generated anchors for headings. They can also be linked to, and may collide with the explicit anchor labels. In this case, Sphinx will not issue a warning.
When linking to external web links:
`Bug Writing Guidelines <http://developer.mozilla.org/en/docs/Bug_writing_guidelines>`_
When linking to other resources, aim to make documentation be as cursive as possible. This means that users should not have to break mid-guide to search for other information.
3.2.4.5. Breaking up long lines of logs
Add a pipe (|) to break up a long log line such as below:
| 20182 2017-01-30 11:56:41 Process user 127.0.0.1:50568 Account "jan"
logged in.
3.2.4.6. Adding configuration and log examples
Examples of configuration or logs in the documentation should be edited to be more of a real world example.
For example, instead of ‘user’, add a real name such as ‘alice’ or ‘bob’:
[accounts/mark-uuid]
name = mark
enabled = Yes
type = application
group = Staff
description = Staff application account for Mark
home_folder_path = /PATH/TO/MARK/HOME
password = PASSWORD
Ensure to add examples for the text file configuration as first priority, followed by steps in the Local Manager GUI.
The configuration / log examples are added after a narrative description of the example.
3.2.5. Updating the documentation
Narrative documentation may be added for a number of reasons such as:
The process to set up the software needs further explanation.
A Support request is made since the documentation is not clear.
A new feature has been released or modified.
A customer has requested how x can be done, and this can be added to the documentation as it is related to the software.
A commonly asked sales request about the software and the documentation is added as the publicly-available answer.
Tips when updating documentation:
When creating a new page, add the page name in a doctree (ie index.rst).
See the towncrier repo for news fragments and the extensions to use.
Documentation changes is usually .ignore with the internal ID.
Release notes are tied to a specific version so that changes are linked to a version of the product.
Further details about generating and building documentation is found in the chevah server repository.
3.2.5.1. Communicating command-line syntax
Use the following convention:
$ client-shell webdavs://user@acme.onmicrosoft.com@acme.sharepoint.com -p 'password'
> connect
# useradd chevah
# groupadd chevah
$ means a non-root user.
# is a root user.
> means a client-shell command.
3.2.6. Marketing / Promotional Materials
Promotions and marketing materials are mainly located in the main website.
It should be as generic and non-technical as possible with links to the Documentation for more in-depth / technical information.
3.2.6.1. Announcing a new release to the email list
After the website is updated and News item published, we send a newsletter:
Go to Campaigns in Mailchimp.
Select ‘Replicate’ besides ‘NEW: ACME Release Announcement’. If it is a security bugfix, use the Security Advisories email list.
Select the News Announcements email list.
Update the subject and email with the News text used to announce the new release. You can use the text in the News article.
Select Send. Before sending the final email, preview first by going to ‘Preview and Send’ on the top menu. Select ‘Send a test email’.
3.2.7. Known Issues
Known issues are bugs/defects with are acknowledge by the development team.
The page is useful for handling Support queries. For example, if a customer finds a problem with the software, check that the problem exists in the Known Issues list first.
If there is an existing issues, then the customer can continue using the product as long as there is also a workaround provided in the Known Issues page.
Known Issues will include a reference to the internal bug ID which provided further details about those issues.
3.2.8. Mock ups and designs for the website
If a change involves a design or content addition (such as an image carousel in JS), it is a good idea to write/mock up the content first before coding.
In this way, you can check to see what type of code work should be done to best communicate the content.
Please go to the ‘design’ repository for sample images and screenshots to use and add your own samples.
If raw HTML needs to be used, see if custom directives can be used such as:
:call_for_action: Ready to install our product?
:call_for_action_link: /pricing/?utm_source=client&utm_campaign=clientbtn&utm_medium=btn#id1
:call_for_action_button: Ask for a trial
For documentation pages, please do not add raw HTML as the format is designed to be converted into multiple other formats.