|
| 1 | +Contributing to documentation is a great way to get started as a contributor to open-source projects, no matter your level of experience. |
| 2 | + |
| 3 | +We welcome, encourage and appreciate contributions from our user community in the form of suggestions, fixes and constructive feedback. Whether you are new to Ceph and want to highlight something you found confusing, or you’re an expert and want to create a “how-to” guide to help others, we will be happy to work with you to make our documentation better for everybody. |
| 4 | + |
| 5 | +Leave a comment on the Discourse forum post or talk to us on our [Matrix](https://app.element.io/#/room/#ceph-general:ubuntu.com) channel. |
| 6 | + |
| 7 | +We hope to make it as easy as possible to contribute. If you feel something is unclear, wrong, or broken, please don’t hesitate to leave a comment in the Matrix room. |
| 8 | + |
| 9 | +## Editing on Discourse |
| 10 | + |
| 11 | +The Charmed Ceph documentation is published via our [Discourse forum](https://discourse.ubuntu.com/c/ceph/52) hosted at [https://discourse.ubuntu.com/](https://discourse.ubuntu.com/). |
| 12 | + |
| 13 | +Every documentation page is published from an equivalent [`doc` category](https://discourse.ubuntu.com/c/documentation/ceph-docs/53) forum post. Each forum post can be accessed from the [Help improve this document in the forum](https://discourse.ubuntu.com/c/ceph/docs/53) link at the bottom of every page of our documentation. |
| 14 | + |
| 15 | +Feel free to improve any documentation topic; pages are freely editable within the forum itself. Just click on the *Edit* button at the bottom of the documentation article forum post: |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | + |
| 20 | +Documentation is written in the [Markdown](https://daringfireball.net/projects/markdown/syntax) format [supported by Discourse](https://meta.discourse.org/t/post-format-reference-documentation/19197/2). |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +### New users |
| 25 | + |
| 26 | +If you are a new Discourse user, your capabilities will be temporarily limited. Discourse uses a trust system that grants experienced users more rights over time. New users start at Trust Level 0, but quickly get to Trust Level 1 where all new user restrictions are removed and they can create and edit our documentation freely. |
| 27 | + |
| 28 | +Trust Level 1 is attained by: |
| 29 | + |
| 30 | +* Entering at least 5 topics |
| 31 | +* Reading at least 30 posts |
| 32 | +* Spending a total of 10 minutes reading posts |
| 33 | + |
| 34 | +Users at Trust Level 1 can: |
| 35 | + |
| 36 | +* Edit wiki posts |
| 37 | +* Use all core Discourse functions; all new user restrictions are removed |
| 38 | +* Send private messages |
| 39 | +* Upload images and attachments |
| 40 | +* Flag posts to alert moderators |
| 41 | +* Mute other users |
| 42 | + |
| 43 | +## Diátaxis |
| 44 | + |
| 45 | +Our documentation content, style and navigational structure follows the [Diátaxis](https://diataxis.fr/) systematic framework for technical documentation authoring. This framework splits documentation pages into tutorials, how-to guides, reference material and explanatory text: |
| 46 | + |
| 47 | +* **Tutorials** are lessons that accomplish specific tasks through *doing*. They help with familiarity and place users in the safe hands of an instructor. |
| 48 | +* **How-to guides** are recipes, showing users how to achieve something, helping them get something done. A *How-to* has no obligation to teach. |
| 49 | +* **Reference** material is descriptive, providing facts about functionality that is isolated from what needs to be done. |
| 50 | +* **Explanation** is discussion, helping users gain a deeper or better understanding of Charmed Ceph, as well as how and why Charmed Ceph functions as it does. |
| 51 | + |
| 52 | +To learn more about our Diátaxis strategy, see [Diátaxis, a new foundation for Canonical documentation](https://ubuntu.com/blog/diataxis-a-new-foundation-for-canonical-documentation). |
| 53 | + |
| 54 | +Improving our documentation and applying the principles of Diátaxis are on-going tasks. There’s a lot to do, and we don’t want to deter anyone from contributing to our docs. If you don’t know whether something should be a tutorial, how-to, reference doc or explanatory text, either ask on the forum or publish in the category you think is best. Changes are easy to make, and every contribution helps. |
| 55 | + |
| 56 | +## Open Documentation Academy |
| 57 | + |
| 58 | +Charmed Ceph is a proud member of the [Canonical Open Documentation Academy](https://github.com/canonical/open-documentation-academy) (CODA), an initiative led by the documentation team at Canonical to provide help, advice, mentorship, and dozens of different tasks to get started on, within a friendly and encouraging environment. |
| 59 | + |
| 60 | +A key aim of this initiative is to help lower the barrier into successful open-source software contribution, by making documentation into the gateway, and it’s a great way to make your first open source documentation contributions to Charmed Ceph. |
| 61 | + |
| 62 | +But even if you’re an expert, we want the academy to be a place to share knowledge, a place to get involved with new developments, and somewhere you can ask for help on your own projects. |
| 63 | + |
| 64 | +The best way to get started is with our [task list](https://github.com/canonical/open-documentation-academy/issues) . Take a look, bookmark it, and see our [Getting started](https://discourse.ubuntu.com/t/getting-started/42769) guide for next steps. |
| 65 | + |
| 66 | +Stay in touch either through the task list, or through one of the following locations: |
| 67 | + |
| 68 | +* Our [discussion forum](https://discourse.ubuntu.com/c/open-documentation-academy) on the Ubuntu Community Hub. |
| 69 | +* In the [Matrix](https://matrix.to/#/#documentation:ubuntu.com) room for interactive chat. |
| 70 | +* [Follow us on Fosstodon](https://fosstodon.org/@CanonicalDocumentation) for the latest updates and events. |
| 71 | + |
| 72 | +If you’d like to ask us questions outside of our public forums, feel free to email us at [email protected]. |
| 73 | + |
| 74 | +In addition to the above, we have a weekly Community Hour starting at 16:00 UTC every Friday. Everyone is welcome, and links and comments can be found on the [forum post](https://discourse.ubuntu.com/t/documentation-office-hours/42771). |
| 75 | + |
| 76 | +Finally, subscribe to our [Documentation event calendar](https://calendar.google.com/calendar/u/0?cid=Y19mYTY4YzE5YWEwY2Y4YWE1ZWNkNzMyNjZmNmM0ZDllOTRhNTIwNTNjODc1ZjM2ZmQ3Y2MwNTQ0MzliOTIzZjMzQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20). We’ll expand our Community Hour schedule and add other events throughout the year. |
| 77 | + |
| 78 | +### Agreements |
| 79 | + |
| 80 | +Everyone involved with CODA needs to follow the words and spirit of the [Ubuntu Code of Conduct v2.0](https://ubuntu.com/community/ethos/code-of-conduct). By participating, you implicitly agree to abide by this code of conduct. |
| 81 | + |
| 82 | +If this is the first time you are contributing to a Canonical project, you will need to sign the [Canonical Contributor Licence Agreement](https://ubuntu.com/legal/contributors) before your contribution can be considered for inclusion within our project. If you have already signed it, e.g. when contributing to another Canonical project, you do not need to sign it again. |
| 83 | + |
| 84 | +This licence protects your copyright over your contributions, including the right to use them elsewhere, but grants us (Canonical) permission to use them in our project. |
| 85 | + |
| 86 | +### Identifying suitable task |
| 87 | + |
| 88 | +The academy uses issue labels to give the contributor a glimpse into the task and what it requires, including the type of task, skills or level of expertise required, and even the size estimation for the task. You can find tasks of all sizes in the academy issues list. |
| 89 | + |
| 90 | +From small tasks, such as replacing outdated terminology, checking for broken links, testing a tutorial or ensuring adherence to the [Canonical documentation style guide](https://docs.ubuntu.com/styleguide/en); to medium-sized tasks like, converting documentation from one format to another, or migrating the contents of a blog post into the official documentation; to more ambitious tasks, such as adding a new *How-to* guide, restructuring a group of documents, or developing new tests and automations. |
| 91 | + |
| 92 | +### Completing and closing tasks |
| 93 | + |
| 94 | +When a task has been completed to your satisfaction, we’ll ask the contributor whether they would prefer to merge their work into your project themselves, or leave this to the project. |
| 95 | + |
| 96 | +### Recognition |
| 97 | + |
| 98 | +After successfully completing a task, we’ll give credit to the contributor and share their success in our forums, on the pages themselves, and in our news updates and release notes. |
| 99 | + |
| 100 | +## Guidance for writing |
| 101 | + |
| 102 | +Consistency of writing style in documentation is vital for a good user experience. To accommodate our audience with a huge variation in experience, we: |
| 103 | + |
| 104 | +* write with our target audience in mind |
| 105 | +* write inclusively and assume very little prior knowledge of the reader |
| 106 | +* link or explain phrases, acronyms and concepts that may be unfamiliar, and if unsure, err on the side of caution |
| 107 | +* adhere to the style guide |
| 108 | + |
| 109 | +### Language |
| 110 | + |
| 111 | +Canonical previously used British (GB) English, so you may notice that older documentation is in this format. However, we have recently switched to US English. It's a good idea to set your spellchecker to `en-US`; which will pick up most of of the inconsistencies. If it doesn't, they will be picked up in review by the documentation team. |
| 112 | + |
| 113 | +There are many small differences between UK and US English, but for the most part, it comes down to spelling. |
| 114 | +Some common differences are: |
| 115 | + |
| 116 | +* the *ize* suffix in preference to *ise* (e.g. capitalize rather than capitalise) |
| 117 | +* *our* instead of *or* (as in color and colour) |
| 118 | +* licence as both a verb and noun |
| 119 | +* catalog rather than catalogue |
| 120 | +* dates take the format 1 January 2013, 1-2 January 2025 and 1 January \- 2 February 2025 |
| 121 | + |
| 122 | +### Acronyms |
| 123 | + |
| 124 | +Acronyms should always be capitalized. |
| 125 | + |
| 126 | +They should always be expanded the first time they appear on a page, and then can be used as acronyms after that. E.g. OSD should be shown as Object Storage Daemon (OSD), and then can be referred to as OSD for the rest of the page. |
| 127 | + |
| 128 | +### Links |
| 129 | + |
| 130 | +The first time you refer to a package or other product, you should make it a link to either that product’s website, or its documentation, or its manpage. |
| 131 | + |
| 132 | +Links should be from reputable sources (such as official upstream docs). Try not to include blog posts as references if possible. And, always verify that the links are correct and accurate. |
| 133 | + |
| 134 | +Try to use inline links sparingly. If you have a lot of useful references you think the reader might be interested in, feel free to include a “Further reading” section at the end of the page. |
| 135 | + |
| 136 | +### Writing style |
| 137 | + |
| 138 | +Try to be concise and to-the-point in your writing. |
| 139 | + |
| 140 | +It’s alright to be a bit light-hearted and playful in your writing, but please keep it respectful, and don’t use emoji (they don’t render well in documentation, and may not be deemed professional). |
| 141 | + |
| 142 | +It’s also good practice not to assume that your reader will have the same knowledge as you. If you’re covering a new topic (or something complicated) then try to briefly explain, or link to supporting explanations of, the things the typical reader may not know, but needs to (refer to the Diátaxis framework to help you decide what type of documentation you are writing and the level and type of information you need to include, e.g. a tutorial may require additional context but a how-to guide can skip some foundational knowledge \- it is safer to assume some prior knowledge). |
| 143 | + |
| 144 | +## Markdown elements |
| 145 | + |
| 146 | +### Sections and headings |
| 147 | + |
| 148 | +Avoid skipping header levels in your document structure, i.e., a level 2 header (##) should be followed by a level 3 sub-header (###) not level 4. |
| 149 | + |
| 150 | +``` |
| 151 | +# Heading level 1 |
| 152 | +
|
| 153 | +## Heading level 2 |
| 154 | +
|
| 155 | +### Heading level 3 |
| 156 | +
|
| 157 | +#### Heading level 4 |
| 158 | +``` |
| 159 | + |
| 160 | +Always include some text between headers if you can. You can see this demonstrated between this section’s heading and the one above it (Markdown elements). It looks quite odd without text to break the headers apart! |
| 161 | + |
| 162 | +### Lists |
| 163 | + |
| 164 | +For a numbered list, use 1. in front of each item. The numbering will be automatically rendered, so it makes it easier for you to insert new items in the list without having to re-number them all: |
| 165 | + |
| 166 | +``` |
| 167 | +1. This is the first item |
| 168 | +
|
| 169 | +1. This is the second |
| 170 | +
|
| 171 | +1. This is the third |
| 172 | +``` |
| 173 | + |
| 174 | +Unless a list item includes punctuation, don’t end it with a full stop. If one item in a list needs a full stop, add one to all the items in that list. |
| 175 | + |
| 176 | +### Code blocks |
| 177 | + |
| 178 | +Enclose a code block with three backticks: |
| 179 | + |
| 180 | +```text |
| 181 | +
|
| 182 | + ```yaml |
| 183 | +
|
| 184 | + Some code block here |
| 185 | +``` |
| 186 | +``` |
| 187 | +``` |
| 188 | + |
| 189 | + |
| 190 | +Use separate command input blocks from command output blocks. We do this because we have a “copy to clipboard” feature in the documentation, and it’s more convenient for the reader to copy the code if it only contains the input. |
| 191 | + |
| 192 | +Avoid using a command line prompt (e.g. $ or #) in an input block if possible, and precede the output block with some kind of text that explains what’s happening. For example: |
| 193 | + |
| 194 | +```bash |
| 195 | + |
| 196 | +Juju list models |
| 197 | + |
| 198 | +``` |
| 199 | + |
| 200 | +Produces the following output: |
| 201 | + |
| 202 | +```text |
| 203 | +
|
| 204 | +Model Cloud/Region Type Status Machines Units Access Last connection |
| 205 | +
|
| 206 | +ceph-charms\* localhost/localhost lxd available 3 3 admin 15 minutes ago |
| 207 | +
|
| 208 | +controller localhost/localhost lxd available 1 1 admin just now |
| 209 | +
|
| 210 | +``` |
| 211 | + |
| 212 | +It can also be helpful to orient the reader with what they should be seeing if you can include examples. |
| 213 | + |
| 214 | +Use a single backtick to mark inline commands and other string literals, like `paths/to/files`. |
0 commit comments