This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • Getting Started Writing Documentation
Skip to end of metadata
Go to start of metadata

The page is about writing or updating the source 'text' of the CloudStack documentation. If you are interested in publish (updating) the public visible rendering of the source, please see the Publishing Documentation Via Read The Docs guide.

Resources

Please see here for an overview of the resources that you may need to use to create or update documentation.

Documentation Source Repos

Consolidated Documentation can be found in GitHub here:

https://github.com/apache/cloudstack-documentation/

What and Why Documentation

The CloudStack community is great at adding new features to CloudStack that make it more useable and flexible with every release.  However, it is almost just as important to inform the users of CloudStack that these features exist and how to use them.  Especially when features have been changed to include new functionality or cause changes the previous way of working.

When writing documentation, one must put oneself in the shoes of the user is trying to use CloudStack to achieve an objective or is exploring cloudstack to understand what it does and how it does it.  Many users will not have the wider background of either the developer or the document writer, and therefore will need clear and concise step-by-step instructions explaining  what a feature does and how to use it.

Sphinx

The documentation in written in 'Sphinx'. For small updates, you don't need to be too familiar with Sphinx, but Sphinx gives the documentation its shape and hierarchy and looks after links and references between documents or sections. If you are trying to relate one section to another, or create new sections, which would then be visible as a separate section in the 'contents' then you will need to look at Sphinx documentation rather than RST (see below).

reStructuredText

The authoring language that is used in the ACS CloudStack Documentation is reStructuredText (RST).  The authoring language allows the writer to denote sections of text as headings or paragraphs, in bold or italics. as well underling or 

the resources page has some links to help you getting started writing in that format.  

Read The Docs

Rather than an instruction, read the docs is a service which publishes versioned documentation.  It is linked to the cloudstack Github documentation repositories, and will build the documentation in the form seen at 'http://docs.cloudstack.apache.org/' from the source 'text' which we commit to Github.  Read the docs applies a theme to the source text, as well as generating navigation menus for viewers of the site.

Writing Documentation Basics

Workflow

Here are the steps to create a PR the 

  1. Clone the documentation repo
  2. Switch to the correct branch (master for a future version)
  3. Update (or add) the section that you're working on.
  4. Double check the reStructured Text using a proofing tool (see resources) to ensure that it looks as you'd expect.
  5. Commit your changes locally
  6. Create a PR from your repo to the ACS documentation repo
  7. Ping people to get their attention to get it merged.
  8. (Possibly ping people again if required)
  9. Remember to merge to master AND the release branch if you've documented something in a release branch that will also be applicable to new versions of CloudStack as well. 

Basic Syntax

Headings and Sections

To denote a heading or section RST uses underlining on the next line with a given character, the number of characters in the underline should be at least the same number of characters as text above.

This is an RST Heading
======================

To denote different levels of heading, you change the character used.  You must be consistent ie always use the same character for heading 2. While which character you use for what is not mandated, there is a guide to these headings here:

http://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html

References/Bookmarks

.. _this-is-link-to-a-heading               <-- marker
:ref:`this-is-link-to-a-heading` <-- reference to marker

If you are linking to a 'bookmark' that does not precede a header you have to add a caption of your own:

.. _this-is-link-to-a-bookmark                                                  <-- marker
:ref:`section about bookmarks <this-is-link-to-a-bookmark>` <-- reference to marker + caption

Images

images are inserted by adding the required image file to /_static/images/ in the repo and linking as follows:

.. image:: /_static/images/zone-overview.png

or if you want to control positioning and add a caption, use a figure.

.. figure:: /_static/images/zone-overview.png

Code Blocks

to add a code block use the flowing syntax (note the indentation)

.. code-block:: bash
   cloudstack-setup-database cloud:cloud@localhost --deploy-as=root:password@localhost

If the block contains a substitution, use parsed-literal (although watch out for special characters)

.. parsed-literal::
   yum install cloudstack-|version|

Includes

You can modularise the source text by using include to stop any one document becoming too bloated

.. include:: _sysvm_restart.rst

 

Creating Diagrams

TODO


Advanced Information

Releases and Versions

The conf.py file in the root of the documentation holds two variables (among other things), release and version.

Version is the short 'version' of CloudStack that the documentation is referring to (ie 4.11)

Release is the long 'version' of CloudStack that the documentation is referring to (ie. 4.11.1.0)

These are referenced in the source text as |version| and |release|.  Updating these in the conf.py should update the vast majority of references to versions/releases in the compiled docs.

Global Substitutions

In the root of the documentation source, there is a file called _global.rst.  This file is referred to in conf.py and is appended to every page automatically by Sphinx.  There is no need to explicitly include this file in the source pages.

This file contains substitutions which can be used globally, including URLs to the 'current' system VM templates and URL of the main CloudStack logo.  Where document writers find a reference which is often repeated and/or needs to be changed from time to time, it would be helpful if they could move the substitution to the global file and update the pointers throughout the documentation.

When writing documentation it is advisable to check the global substitution file 1st to know when substitutions are made globally rather than locally.


Documentation Writing Guidelines

Write all of the wordsDon't abbreviate sentences as one might when speaking.  It often makes a sentence hard to read, or changes the meaning of the sentence
Avoid ambiguity of the object to which you are referring

When there are more that one object in a sentence, ensure that it is explicitly stated which object is being referred to in subsequent statements.
"The scripts currently updates the firewall rules on the virtual routers, they will be updated to....."

This could be stating that either the firewall rules, the virtual routers or the scripts are being updated.  This should read:

"The scripts currently updates the firewall rules on the virtual routers, the scripts will be updated to....."

Abbreviations
  • Don't use abbreviations unless they are generally accepted in English - they make documentation and blogs look unprofessional.
  • The only exceptions to this are:
    • When they are used in code/log file output.
    • If you have a document table with very limited space and you try to get table headers to line up.

Examples of bad abbreviations:

  • "mgmt." instead of management
  • "fw." instead of firewall 
  • "srvr" for server
  • "auth" instead of "authentication" or "authorisation"
  • "env" instead of "environment"
Acronyms

Acronyms should be in upper case:

  • "VMs" rather than "vms"
  • "IP" rather than "ip"
  • "SSVM" and not "ssvm"
  • "ID" rather than "id"

Etc.

CapitalisationDon't capitalise server roles mid-sentence - they are not proper names - hence use "CloudStack management server" rather than "CloudStack Management Server". 
The same goes for other components like "firewall", "network switch", "storage array", etc.
This includes 'virtual router' and 'secondary storage VM'.




  • No labels