You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

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

https://github.com/apache/cloudstack-docs-install.git is the install guide

https://github.com/apache/cloudstack-docs-admin.git is the current admin manual.

https://github.com/apache/cloudstack-docs-rn.git is the release notes for individual releases

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.

Writing Documentation Basics

Here are the steps to create a PR the 

  1. Clone the documentation repo that you wish to update
  2. Update (or add) the section that you're working on.
  3. Double check the .rst using a proofing tool (see resources) to ensure that it looks as you'd expect.
  4. Commit your changes locally
  5. Create a PR against the repo that you've updated
  6. Ping people to get their attention to get it merged.
  7. (Possibly ping people again if required)


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