Versions Compared

Old Version 3

changes.mady.by.user Paul Angus

Saved on

compared with

New Version 4

changes.mady.by.user Paul Angus

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  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 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'.