Writing style guide¶
This guide describes the writing style for the OpenStack Charms documentation sources.
The below pages provide specific guidance for the two writing formats used with the OpenStack Charms project:
Juju application names are not formatted:
“the nova-compute application”
“the nova-compute charm”
“the nova-compute unit”
Cited bugs are expressed as hyperlinks and, depending on Launchpad or GitHub bug trackers, are of the form:
Use monospace format for:
unit names: “the
action names: “the
references to utilities/programs: “like
paths: “in the
command options: “the
charm configuration options: “the
Use a maximum line length of 79 characters.
Use single quotes for values: “the option’s value is ‘br-ex:eth1’”.
Use bold and italics very sparingly.
Use single spaces between sentences.
Use hyperlink labels at the bottom of a page.
An admonishment should contain drop-in, self-sufficient text. That is, it should not depend on the main-body (surrounding) text to be intelligible. In this way, if the admonishment becomes no longer applicable, removing it will not adversely affect the logic of the surrounding text.
Capitalisation should be minimised:
Use a capital letter for just the first word of all section headers
Use capital letters for any proper nouns or acronyms, as usual
OpenStack services such as Nova
Project names like HAProxy or OpenStack
Be mindful of including information that is expected to become out of date, such as citing bugs or listing things that will surely change. It might be better to simply omit some information. For instance, do not start a list of versions thinking that it will be maintained by someone. To avoid:
Firefly is available in Trusty, Hammer is in Trusty-Juno (end of life), Trusty-Kilo, Trusty-Liberty, and Jewel is available in Trusty-Mitaka.
The use of temporal expressions such as “not yet”, “currently”, and “at the time of writing”, or closely related status terms such as “experimental”, should be avoided entirely. To avoid:
The charm should not yet be used in the following scenarios... ... but note that this is an experimental feature.
Release notes are an exception as the temporal context is understood:
The charm now supports feature X...
If at all possible, simply give numbers (e.g. versions, dates) to guide a reader, but do not hardcode versions into instructions. Explain with words and include versions only as part of an example command.
If transient information is categorically needed then express it with an admonishment. The use of admonishments also makes temporal information much easier to identify during documentation reviews.
All extra whitespace should be removed, especially at the end of lines.
Two trailing spaces is valid Markdown; it forces a carriage return. This is very rarely required and should be avoided whenever possible.
Some messaging is used repeatedly due to situations that arise regularly. This section is an attempt at making a consistent set of snippets for such cases.
Preview charms or functionality¶
Use an informational admonishment to convey tech-preview status for a charm, or functionality for an existing charm:
The MySQL 8 charms are in a tech-preview state and are ready for testing. They are not production-ready. Charmed Swift global cluster functionality is in a tech-preview state and is ready for testing. It is not production-ready.
Version requirements or limitations¶
Use an informational admonishment to convey a software requirement or limitation for a charm, or functionality for an existing charm:
BlueStore compression is supported starting with Ceph Mimic.
The following deploy or add-unit command syntax and ordering of options should be observed:
juju deploy -n <X> --to <Y> --config <option=Z> ... juju add-unit -n <X> --to <Y> --config <option=Z> ...
Multi-line commands should have their extra lines indented by three spaces:
openstack role add --user 1ea06b07c73149ca9c6753e07c30383a \ --project Project1 Member