Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 1 | # Matter Documentation Style Guide |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 2 | |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 3 | Matter documentation lives here: |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 4 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 5 | - **GitHub** — All guides and tutorials across the complete |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 6 | [Matter organization](https://github.com/project-chip). |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 7 | |
Vivien Nicolas | fbbf127 | 2020-10-02 20:08:13 +0200 | [diff] [blame] | 8 | See |
| 9 | [CONTRIBUTING.md](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md) |
| 10 | for general information on contributing to this project. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 11 | |
| 12 | ## Location |
| 13 | |
Gaute Svanes Lunde | e7347ea | 2023-01-09 19:43:07 +0100 | [diff] [blame] | 14 | Place all documentation contributions in the appropriate location in the `docs` |
| 15 | directory. Most contributions should go into the `/docs/guides` subdirectory, |
| 16 | which covers conceptual and usage content. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 17 | |
| 18 | Current documentation structure: |
| 19 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 20 | | Directory | Description | |
| 21 | | ----------------------- | -------------------------------------------------------------------------------------------- | |
| 22 | | `/actions` | Custom GitHub actions | |
| 23 | | `/docs/guides` | Conceptual or usage content that doesn't fit within a subdirectory, and high-level tutorials | |
| 24 | | `/docs/guides/images` | All images included in guide content | |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 25 | | `/docs/guides/profiles` | Content describing or illustrating use of Matter profiles | |
| 26 | | `/docs/guides/test` | Content related to testing Matter | |
| 27 | | `/docs/guides/tools` | Content describing or illustrating use of Matter tools | |
| 28 | | `/docs/guides/primer` | Matter Primer content | |
| 29 | | `/docs/presentations` | PDF presentations on Matter features | |
| 30 | | `/docs/specs` | PDFs of Matter specifications | |
| 31 | | `/images` | Top-level Matter images, such as logos | |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 32 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 33 | If you are unsure of the best location for your contribution, create an Issue |
| 34 | and ask, or let us know in your Pull Request. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 35 | |
| 36 | ## Style |
| 37 | |
| 38 | Style to come |
| 39 | |
| 40 | ## Links |
| 41 | |
| 42 | For consistency, all document links should point to the content on GitHub. |
| 43 | |
| 44 | The text of a link should be descriptive, so it's clear what the link is for: |
| 45 | |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 46 | ## Markdown guidelines |
| 47 | |
Grzegorz Ferenc | bae3e7d | 2021-10-19 15:49:45 +0200 | [diff] [blame] | 48 | Use standard Markdown when authoring Matter documentation. While HTML may be |
| 49 | used for more complex content such as tables, use Markdown as much as possible. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 50 | |
| 51 | > Note: Edit this file to see the Markdown behind the examples. |
| 52 | |
| 53 | ### Headers |
| 54 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 55 | The document title should be an h1 header (#) and in title case (all words are |
| 56 | capitalized). All section headers should be h2 (##) or lower and in sentence |
| 57 | case (only the first word and proper nouns are capitalized). |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 58 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 59 | The best practice for document clarity is to not go lower than h3, but h4 is |
| 60 | fine on occasion. Try to avoid using h4 often, or going lower than h4. If this |
| 61 | happens, the document should be reorganized or broken up to ensure it stays at |
| 62 | h3 with the occasional h4. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 63 | |
| 64 | ### Command line examples |
| 65 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 66 | Feel free to use either `$` or `%` to preface command line examples, but be |
| 67 | consistent within the same doc or set of docs: |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 68 | |
| 69 | ``` |
| 70 | $ git clone https://github.com/project-chip/connectedhomeip.git |
| 71 | % git clone https://github.com/project-chip/connectedhomeip.git |
| 72 | ``` |
| 73 | |
| 74 | ### Terminal prompts |
| 75 | |
lzgrablic02 | a9f7b80 | 2021-12-16 03:24:03 -0500 | [diff] [blame] | 76 | If you need to use a full terminal prompt with username and hostname, use the |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 77 | format of `root@{hostname}{special-characters}#`. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 78 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 79 | For example, when logged into a Docker container, you might have a prompt like |
| 80 | this: |
| 81 | |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 82 | ``` |
| 83 | root@c0f3912a74ff:/# |
| 84 | ``` |
| 85 | |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 86 | ### Commands and output |
| 87 | |
| 88 | All example commands and output should be in code blocks with backticks: |
| 89 | |
| 90 | ``` |
| 91 | code in backticks |
| 92 | ``` |
| 93 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 94 | ...unless the code is within a step list. In a step list, indent the code |
| 95 | blocks: |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 96 | |
| 97 | code indented |
| 98 | |
| 99 | ### Code blocks in step lists |
| 100 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 101 | When writing procedures that feature code blocks, indent the content for the |
| 102 | code blocks: |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 103 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 104 | 1. Step one: |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 105 | |
| 106 | $ git clone https://github.com/project-chip/connectedhomeip.git |
| 107 | $ cd connectedhomeip |
| 108 | |
| 109 | 1. Step two, do something else: |
| 110 | |
| 111 | $ ./configure |
| 112 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 113 | For clarity in instructions, avoid putting additional step commands after a code |
| 114 | sample within a step item. Instead rewrite the instruction so this is not |
| 115 | necessary. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 116 | |
| 117 | For example, avoid this: |
| 118 | |
| 119 | 1. Step three, do this now: |
| 120 | |
| 121 | $ ./configure |
| 122 | |
| 123 | And then you will see that thing. |
| 124 | |
| 125 | Instead, do this: |
| 126 | |
| 127 | 1. Step three, do this now, and you will see that thing: |
| 128 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 129 | $ ./configure |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 130 | |
| 131 | ### Inline code |
| 132 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 133 | Use backticks for `inline code`. This includes file paths and file or binary |
| 134 | names. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 135 | |
Pankaj Garg | 43c9c68 | 2020-03-20 15:06:18 -0700 | [diff] [blame] | 136 | ### Code Comments |
| 137 | |
| 138 | Use uppercase `CHIP` in comments, as it is an acronym. |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 139 | |
Justin Wood | c9bbb25 | 2020-03-03 10:03:58 -0800 | [diff] [blame] | 140 | Supported keywords: |
| 141 | |
Justin Wood | 0a9545e | 2020-04-20 18:15:21 -0700 | [diff] [blame] | 142 | | Keyword | Description | |
| 143 | | ------- | ----------- | |
| 144 | | alarm | Alarm | |