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.
Please see here for an overview of the resources that you may need to use to create or update documentation.
The Documentation for CloudStack is currently split across three separate repositories, which are maintained over three unconnected projects in the Read The Docs service.
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
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.
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/projects/cloudstack-administration/en/latest/' 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.
The authoring language that is used in the ACS CloudStack Documentation is reStructuredText (RST), the resources page has some links to help you getting started writing in that format.
Here are the steps to create a PR the
TODO
Write all of the words | Don'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. 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 |
Examples of bad abbreviations:
| |
Acronyms | Acronyms should be in upper case:
Etc. | |
Capitalisation | Don'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'. | |