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

Compare with Current View Page History

« Previous Version 4 Next »

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

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