Our documentation is a community effort, [published][ceph-docs] via the [DIscourse][upstream-discourse] forum hosted at [discourse.ubuntu.com][discourse-ubuntu]. We welcome corrections and enhancements as well as suggestions and constructive criticism. You can modify (almost) any page by visiting the Discourse [Documentation][discourse-ceph-docs] category, where each documentation web page corresponds to a Discourse topic. In addition, every web page has a link that leads directly to its corresponding topic. All you need to do is sign up on the forum. If you're unsure of your intended contribution you can leave a post on the topic in question asking for guidance. Finally, the [Documentation-discuss][discourse-ceph-docs-discuss] Ceph sub-category is available for documentation related subjects. ## Contents - [Writing style](#heading--writing-style) - [Line length](#heading--line-length) - [Emoji](#heading--emoji) - [Source format](#heading--source-format) - [Headings and titles](#heading--headings-and-titles) - [Lists](#heading--lists) - [Tables](#heading--tables) - [Code blocks](#heading--code-blocks) - [Inline code](#heading--inline-code) - [Hyperlinks](#heading--hyperlinks) - [Anchors](#heading--anchors) - [Admonishments](#heading--admonishments) - [Comments](#heading--comments) - [Foldouts](#heading--foldouts) - [Images](#heading--images)

Writing style

Documentation consistency in terms of writing style is vital for a good user experience. Here are some general tips: - define acronyms and concepts–don't assume others are familiar with the subject - use a spell checker - resist being overly formal - resist being overly verbose - verify links and examples - don't repeat what's been covered in other posts - use hyperlinks We adhere to the [Canonical Documentation Style Guide][canonical-doc-style-guide]. In particular: - we use British English (en-GB), for example: - the _ise_ suffix in preference to _ize_ (_capitalise_ rather than _capitalize_) - _our_ instead of _or_ (as in _colour_ and _color_) - license as a verb, licence as a noun - catalogue rather than catalog - dates take the format _1 January 2013_, _1-2 January 2013_ and _1 January - 2 February 2013_

Line length

Discourse honours the line length in its editor. Therefore, ensure that a paragraph does not take on a jagged appearance (long lines mixed with short lines). Use common sense when inserting line breaks so the resulting text "looks good" to the reader.

Emoji

Please do not use emoji in the documentation. They would be published on the web site and that's not appropriate. :woman_shrugging:

Source format

Documentation is written in the [CommonMark Markdown][upstream-commonmark] format [supported by Discourse][upstream-commonmark-format]. Mostly, you don't need to worry about the syntax. You can simply use the style toolbar in the Discourse topic editing window to mark the elements you need. [note type="positive" status="Pro tip"] If you can't get the results you want try to find a similar post and use the following URL format to view its raw markdown `https://forum.example.com/raw/{topic-id}/{post-id}`. See [the current post][documentation-guidelines-raw] for an example. [/note] Individual elements are now explained. Some formatting can be achieved in more than one way. Kindly use the methods described in order to maintain consistency throughout the documentation.

Headings and titles

```markdown ## Subheading within a document ### Subheading of a subheading ``` We don't use the top-level heading (`# Heading`) as the topic title serves this purpose. Headings and subheadings should use _sentence case_, which means the first letter is the only one capitalised. Proper nouns and acronyms are exceptions.

Lists

For a bullet list, use a hyphen ( - ). Sub-lists will use an hyphen indented at least 2 spaces: ```markdown We (mostly) adhere to the Ubuntu style guide, for example: - we use British English (en-GB): - the _ise_ suffix in preference to _ize_ ``` For a numbered list, use `1. ` to precede each item. The numbering will be rendered automatically. One benefit is that it's simple to insert new items: ```markdown 1. This is the first item 1. This is the second 1. This is the third 1. This is a sub-list ``` The indent here needs to be at least 3 spaces. Unless a list item is particularly long (which should be avoided) and includes punctuation, don't end the item with a full stop. If one item needs a full stop, add one to all the items.

Tables

An example table: heading 1 | heading 2 | heading 3 -|-|- cloud | user | pass type | access | key It is produced by the following markdown: ```markdown heading 1 | heading 2 | heading 3 -|-|- cloud | user | pass type | access | key ``` Use colons for horizontal alignment: heading 1 | heading 2 | heading 3 :-|:-:|-: left | centered | right type | access | key The markdown: ```markdown heading 1 | heading 2 | heading 3 :-|:-:|-: left | centered | right type | access | key ``` Left-aligned is the default, and does not need to be stated. The number of dashes has no effect on the final result.

Code blocks

Enclose a code block with three backticks and include the *type* of code: ```yaml name: gimp version: '2.10.8' summary: GNU Image Manipulation Program ``` The most common code types are: `bash`, `yaml`, `json`, and `text`. The last is like a miscellaneous type. It is often used to display command output and does not highlight anything. [note type="important" status="Note"] The `text` type is usually the best choice as the other types often appear to highlight things randomly from the reader's perspective. [/note] Do separate command input blocks from command output blocks. For input, do **not** use a command line prompt (e.g. `$` or `#`) and precede the output block with some kind of intelligent message: ```bash lsb_release -r ``` Sample output: ```no-highlight Release: 18.04 ```

Inline code

Use a backtick to mark inline commands and other literals. For instance, to create `$SNAP_DATA`: ```markdown For instance, to create `$SNAP_DATA`: ``` For links to internal files or external URLs, use the following format: ```markdown [visible text](url) ``` For internal pages the full URL is not necessary. The below forms will also work for, say, `https://discourse.jujucharms.com/t/clouds/1100`: ```markdown [Clouds](/t/clouds/1100) ``` For linking to headers (see next section 'Anchors'), this can be used: ```markdown [Adding clouds](/t/clouds/1100#heading--adding-clouds) ``` Or, if within the same page: ```markdown [Adding clouds](#heading--adding-clouds) ```

Anchors

To link to a header within the same page or in another page you will need to use HTML tags. Importantly, this will also create header links on the published page so that they can be used universally on the internet. For example, to create a link to the (second-level) destination header of "Adding clouds" edit the header on the destination page (`clouds` here) so it changes from this: ```markdown ## Adding clouds ``` to this: ```markdown

Adding clouds

``` As shown above, base the anchor name (`heading--adding-clouds`) on the destination header (`Adding clouds`), even if this is not strictly required. This is for consistency and logic. Within the same Discourse instance, this can now be linked to with the following URL: ```markdown /t/clouds/1100#heading--adding-clouds ``` Or, if within the same page: ```markdown #heading--adding-clouds ``` External to the Discourse instance (on the internet), a full URL will be needed but with the `#heading--adding-clouds` portion affixed to the end. [note type="caution" status="Warning"] Avoid altering the names of existing anchors as doing so may break existing links to it. It is not obvious what other pages are linking to it. [/note]

Admonishments

To highlight something, you can use *admonishment*. Admonishments are self-contained snippets that are not part of the main flow of the document. They're also used as *sidebars* in printed works. The wording is correct if the admonishment can be understood independently of the body copy and removing it does not impact readers' understanding of the surrounding text. #### Syntax for admonishments Admonishments in Discourse use BBtext markup syntax. Using `[note]` ... `[/note]` draws a box around the contained text. ```markdown [note type="note" status="Note"] An informative note. This box is dark blue. [/note] ``` This produces: [note type="important" status="Note"] An informative note. [/note] You can omit the status header. ```plain [note type="important"] A note without a title. [/note] ``` And its output: [note type="important"] A note without a title. [/note] The `type` parameter is optional, but recommended: ```plain [note] A note that only uses default settings. [/note] ``` And its output: [note] A note that only uses default settings. [/note] #### Types of `[note]` Changing the `type` parameter changes how it is presented to the reader: - `note` - `important` (default) - `caution` - `positive` - `negative` The below examples are produced using type and status combinations of 'caution/Warning', 'positive/High score', and 'negative/Game over', respectively: [note type="caution" status="Warning"] Here be dragons. Uses `caution` type. [/note] [note type="positive" status="High score"] Great work. Uses `positive` type. [/note] [note type="negative" status="Game over"] Please try again. Uses `negative` type. [/note] Hyperlinks cannot be word-wrapped within admonishments. Doing so will not format the links.

Comments

Here we'll explain two ways to leave comments in a page. Doing either will prevent the text from being published on the documentation web site. Firstly, there may be times when a little explanation (to other editors) is required amidst a page. Use standard HTML comment tags: ```markdown ``` Secondly, intended work may get left undone or there may be external circumstances that affect the documentation (e.g. software bugs). These things should also be noted for future editors. Use a TODO list for this within a comment at the very top of a document: ```markdown ```

Foldouts

When a page contains a lot of extraneous information, such as software code or file contents, a *foldout* can be used. This will create a collapsed header, which, when clicked, will expand to display all the content below it. ```markdown [details=This is the visible header] This text is completely hidden. The reader clicks the header to reveal its contents. [/details] ``` The above will produce: [details=This is the visible header] This text is completely hidden. The reader clicks the header to reveal its contents. [/details]

Images

An image should be easier to understand than text, reinforce concepts being discussed in the topic, and break the monotony of a long stream of paragraphs. When making images: - do not crop your images too aggressively; add a little extra to provide context - use a resolution high enough to make text legible and work with high-DPI displays - a wide aspect ratio fits better with the width of the rendered documentation - save with lossless compression, such as PNG for screenshots (JPG is acceptable for photos) Images can be simply dragged and dropped into the edit field, or uploaded (local device or a public URL) via the toolbar icon. It can be helpful to edit the description field of an image link after uploading: ```markdown ![description of image]() ``` To resize images based on pixels or a percentage of pixels use the following syntax: ```markdown ![description of image]|200x200]() ![description of image]|200x200,50%]() ![description of image]|64x64]() ``` For example: ![rocketship|335x322](upload://7vTeT6goBGK9a1sYRtVpzf4Xzus.png) ![rocketship|335x322,50%](upload://7vTeT6goBGK9a1sYRtVpzf4Xzus.png) ![rocketship|100x104](upload://7vTeT6goBGK9a1sYRtVpzf4Xzus.png) These images are produced with the following: ```markdown ![rocketship|335x322](upload://7vTeT6goBGK9a1sYRtVpzf4Xzus.png) ![rocketship|335x322,50%](upload://7vTeT6goBGK9a1sYRtVpzf4Xzus.png) ![rocketship|100x104](upload://7vTeT6goBGK9a1sYRtVpzf4Xzus.png) ``` [ceph-docs]: https://ubuntu.com/ceph/docs [upstream-discourse]: https://www.discourse.org/ [discourse-ubuntu]: https://discourse.ubuntu.com/ [canonical-doc-style-guide]: https://docs.ubuntu.com/styleguide/en [discourse-ceph-docs]: /c/ceph/docs [discourse-ceph-docs-discuss]: /c/ceph/docs-discuss [upstream-commonmark]: https://commonmark.org/help [upstream-commonmark-format]: https://talk.commonmark.org/t/discourse-is-migrating-to-commonmark/2476 [documentation-guidelines-raw]: /raw/18759/1