Adding new content¶
When software is developed certain documentation criteria must be met in order for the software to be considered feature complete. And like software, a documentation contribution must be implemented correctly.
The practice of modelling one’s contribution on existing pages can be counter-productive as the documentation set may not always be in an ideal state. Therefore, first establish what you want to add and then, based on the available sources, determine where to place it and how to do so.
There is a logical order to this document’s contents. Please go through it sequentially.
Diátaxis¶
The Diátaxis framework is used throughout the documentation wherever appropriate. It provides a conceptual approach to writing, which in turn affects how documentation is created and how a set of pages is organised. Becoming familiar with Diátaxis is the first step to contributing.
The four quadrants of Diátaxis¶
Note
Charmed OpenStack documentation prefers the term “Concepts” in the place of “Explanations”.
Further reading: a conference talk - PyCon Australia 2017
Monolithic vs distributed¶
Now that the Diátaxis framework is understood we can consider what form a contribution can take. It should be clear that a contribution need not be a monolithic piece of work; it can be distributed. For instance, on the same general topic, there can be several interconnected parts such as a conceptual treatment, a howto guide, and a tutorial. Speak to colleagues, discuss with your local documentarian, or chat on the user forum.
Sources¶
Assuming that the specific pieces of work have been identified they each need to be published in the appropriate location, with the right tools, and in the correct format. The following sub-sections provide an outline of each documentation source. A summary of these sources is given on the parent page.
OpenStack Charm Guide¶
The Charm Guide is the main source of information for the OpenStack Charms project. All Diátaxis types are therefore appropriate: Tutorials, Howtos, Concepts, and Reference. The Charm Guide also includes community and project information - categories that fall outside of the Diátaxis framework.
This documentation is created on OpenDev, is under version control (Git), and is written in Sphinx-enhanced reStructuredText.
OpenStack Charms Deployment Guide¶
The Deploy Guide is the main source of information for the charm-by-charm deployment of a Charmed OpenStack cloud. Due to its focussed nature, the only suitable Diátaxis type is Howtos.
This documentation is created on OpenDev, is under version control (Git), and is written in Sphinx-enhanced reStructuredText.
Note
The Deploy Guide is currently in the process of migrating non-deployment related content to the Charm Guide.
OpenStack Charms Admin Guide¶
The Admin Guide is the day-2 operations guide for Charmed OpenStack. Due to its focussed mandate, the only applicable Diátaxis type is Howtos.
This documentation is created on OpenDev, is under version control (Git), and is written in Sphinx-enhanced reStructuredText.
Note
The Admin Guide is currently embedded in the Charm Guide. The intention is to eventually break it out into a separate guide.
Charm READMEs¶
A charm README file specifically encapsulates a charm’s purpose and usage (Diátaxis is not applied).
In order to maintain a consistent structure across all charms, a README template has been made available and should be followed.
This documentation is created on OpenDev, where each charm has its own repository (see OpenStack charms), and is written in Markdown. A README also gets rendered on the its charm’s landing page in the Charmhub (with the Mistune Python parser). See the keystone charm for an example.
Tip
The rendering of a README (into HTML) can be validated with a Markdown viewer.
Charm developer documentation¶
Charm developer documentation is written by developers and for developers. It may include topics such as how to build, enhance, test, or debug a charm. Conceptual documentation that explains the inner workings of a charm is another possibility. Suggested Diátaxis types are Howtos and Concepts.
This documentation is created in Discourse (essentially CommonMark) and is viewed in the Charmhub. See the keystone charm Docs tab for an example.
Writing style¶
Please use the Writing style guide when creating content. Documentation is more clearly understood by users and developers alike when it is implemented in a consistent manner.
Technical accuracy¶
The contribution needs to be technically correct. In particular, if the content is a Howto or a Tutorial then the collection of steps must be tested and verified.
