|
| 1 | +# Documentation style guide |
| 2 | + |
| 3 | +This is a work-in-progress style guide for documentation. There are many things |
| 4 | +not currently covered here, and it is not intended to be a complete manual for |
| 5 | +writing documentation, just a set of pointers to help us achieve a comfortable |
| 6 | +level of consistency. |
| 7 | + |
| 8 | +## Docusaurus |
| 9 | + |
| 10 | +The documentation is written in Markdown and the site is built using Docusaurus. |
| 11 | +In practical terms, if you are familiar with markdown, there isn't really |
| 12 | +anything complicated you need to learn in order to contribute. Docusaurus does |
| 13 | +add some extra elements though, and also may use a slightly different set of |
| 14 | +rules than you are used to. The [Docusaurus |
| 15 | +documentation](https://docusaurus.io/docs/markdown-features) contains a lot of |
| 16 | +useful information on how to use Markdown to create the output you want. |
| 17 | + |
| 18 | +## Branding |
| 19 | + |
| 20 | +Consistency in branding is important for a number of reasons, including the |
| 21 | +protection of trademarks where they apply. For our own products, and those of |
| 22 | +others we mention frequently, the following guidance applies. |
| 23 | + |
| 24 | +**Wokwi**: Use capitals except where using as part of a command. For example, we |
| 25 | +may write about the Wokwi CLI, the command is `wokwi-cli`however. **Wokwi |
| 26 | +Classroom**: Used when referring to the particular academic license scheme. |
| 27 | +Note the capitalization. |
| 28 | + |
| 29 | +### Boards and platforms |
| 30 | + |
| 31 | +Please try to respect other brands also. For example, the chip powering the |
| 32 | +Arduino uno is an "ATmega328p". You have probably seen it so often that it would |
| 33 | +look wrong if someone wrote "Atmega328P". |
| 34 | + |
| 35 | +For the Espressif ESP32 family of microcontrollers, be specific where possible: |
| 36 | +for example, when referring to something particular to a C6 variant of the chip, |
| 37 | +use the full designation, "ESP32-C6". |
| 38 | + |
| 39 | +For supported platforms and components, a useful place to check the correct |
| 40 | +naming is on the [supported hardware |
| 41 | +page](https://docs.wokwi.com/getting-started/supported-hardware) of our own |
| 42 | +docs. |
| 43 | + |
| 44 | +## Contractions |
| 45 | + |
| 46 | +Contractions are very common in spoken English and in many types of writing. |
| 47 | +Avoiding the use of them entirely makes it difficult to achieve a friendly, |
| 48 | +conversational tone. However, do keep to contractions that are commonly |
| 49 | +understood and not part of some regional dialect. |
| 50 | + |
| 51 | +Do use: "can't", "won't", "isn't" ... |
| 52 | +Don't use: "ain't", "gonna" ... |
| 53 | + |
| 54 | +## Headings |
| 55 | + |
| 56 | +Headings are important for navigation, for setting tone and for search indexing. |
| 57 | +Please bear in mind the following: |
| 58 | + |
| 59 | +### Sentence case |
| 60 | + |
| 61 | +All headings and headlines should be sentence case. This means that you |
| 62 | +should only capitalize the first word unless it falls into one of the categories |
| 63 | +outlined below: |
| 64 | + |
| 65 | +- product names |
| 66 | +- company names |
| 67 | +- personal names |
| 68 | +- brands |
| 69 | +- places |
| 70 | + |
| 71 | +**Use:** Build your dreams with Wokwi |
| 72 | +**Don't use:** Build Your Dreams With Wokwi |
| 73 | + |
| 74 | +### Other considerations |
| 75 | + |
| 76 | +- Avoid links in headings |
| 77 | +- Avoid overusing punctuation in headings. Headings should not end with a period/full point/full stop |
| 78 | +- Don't overuse `code` styling in headings - it is rarely useful or pleasant to look at |
| 79 | +- Imperatives should be used for 'How to...' style docs instead of gerunds (i.e. "Create an instance" rather than "Creating an instance") |
| 80 | +- Do not skip levels of heading hierarchy (e.g. following an h1/# with an h3/###) |
| 81 | +- Headings require content and should not be followed directly by a subheading |
| 82 | + |
| 83 | +## Words and phrases to avoid |
| 84 | + |
| 85 | +Try to avoid jargon, long-winded phrases and words with negative |
| 86 | +connotations. |
| 87 | + |
| 88 | +## Code examples in documentation |
| 89 | + |
| 90 | +**Don't** use prompt marks (e.g. `$` or `#`) in code samples. These cause |
| 91 | +problems for users who sometimes mistakenly type them in, or who want to copy |
| 92 | +and paste sections of code. They also encourage poor explanation of the code. |
| 93 | + |
| 94 | +**Do** separate commands and output where appropriate. |
| 95 | + |
| 96 | +## Admonitions |
| 97 | + |
| 98 | +Admonitions (also referred to as "admonishments", "callouts" or "notifications") |
| 99 | +are a device used in documentation to draw attention to a particular statement |
| 100 | +or paragraph of text. Typically their use is to highlight: |
| 101 | + |
| 102 | +- A consequence of performing a particular action |
| 103 | +- An additional source of information which is useful but not required |
| 104 | +- A helpful tip that will save effort/time |
| 105 | +- A reminder of some pre-requisite or restriction |
| 106 | + |
| 107 | +Docusaurus has some built-in styles to make these themed admonitions stand out |
| 108 | +in a consistent way. Check the [Docusaurus documentation about |
| 109 | +admonitions](https://docusaurus.io/docs/markdown-features/admonitions) for more |
| 110 | +details. |
| 111 | + |
| 112 | +## Hyperlinks |
| 113 | + |
| 114 | +Here are some pointers about the general use of links and how to format them correctly. |
| 115 | + |
| 116 | +### General use |
| 117 | + |
| 118 | +Avoid excessive links in the same paragraph or instruction. If you find |
| 119 | +yourself introducing several links in your content, consider listing them in a |
| 120 | +separate section called "Related topics", "Additional resources", or similar. |
| 121 | + |
| 122 | +### Formatting |
| 123 | + |
| 124 | +Make sure either the link text itself or the surrounding sentence provides |
| 125 | +enough context about the contents of the linked section. |
| 126 | + |
| 127 | +Avoid phrases like "this document", "this article", or "click here" as the link |
| 128 | +text. |
| 129 | + |
| 130 | +For example, when referring to a section called "Formatting": |
| 131 | + |
| 132 | +- Use: `See the [formatting guidelines](#formatting) for hyperlinks.` |
| 133 | +- Use: `See the [Formatting section](#formatting) for guidelines about hyperlink formatting.` |
| 134 | +- Avoid: `See [Formatting](#formatting).` |
| 135 | +- Avoid: `See [this section](#formatting).` |
| 136 | + |
| 137 | +Avoid using a URL as the linked text. |
| 138 | + |
| 139 | +- Use: `[Page title](https://page-url.com)` |
| 140 | +- Avoid: `[https://page-url.com](https://page-url.com)` |
0 commit comments