blob: 5f195ed49f8076a29b7a61ef2718535ab9e09461 [file] [log] [blame] [view]
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +02001# Matter Documentation Style Guide
Justin Woodc9bbb252020-03-03 10:03:58 -08002
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +02003Matter documentation lives here:
Justin Woodc9bbb252020-03-03 10:03:58 -08004
Justin Wood0a9545e2020-04-20 18:15:21 -07005- **GitHub** All guides and tutorials across the complete
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +02006 [Matter organization](https://github.com/project-chip).
Justin Woodc9bbb252020-03-03 10:03:58 -08007
Vivien Nicolasfbbf1272020-10-02 20:08:13 +02008See
9[CONTRIBUTING.md](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md)
10for general information on contributing to this project.
Justin Woodc9bbb252020-03-03 10:03:58 -080011
12## Location
13
Gaute Svanes Lundee7347ea2023-01-09 19:43:07 +010014Place all documentation contributions in the appropriate location in the `docs`
15directory. Most contributions should go into the `/docs/guides` subdirectory,
16which covers conceptual and usage content.
Justin Woodc9bbb252020-03-03 10:03:58 -080017
18Current documentation structure:
19
Justin Wood0a9545e2020-04-20 18:15:21 -070020| 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 Ferencbae3e7d2021-10-19 15:49:45 +020025| `/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 Woodc9bbb252020-03-03 10:03:58 -080032
Justin Wood0a9545e2020-04-20 18:15:21 -070033If you are unsure of the best location for your contribution, create an Issue
34and ask, or let us know in your Pull Request.
Justin Woodc9bbb252020-03-03 10:03:58 -080035
36## Style
37
38Style to come
39
40## Links
41
42For consistency, all document links should point to the content on GitHub.
43
44The text of a link should be descriptive, so it's clear what the link is for:
45
Justin Woodc9bbb252020-03-03 10:03:58 -080046## Markdown guidelines
47
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +020048Use standard Markdown when authoring Matter documentation. While HTML may be
49used for more complex content such as tables, use Markdown as much as possible.
Justin Woodc9bbb252020-03-03 10:03:58 -080050
51> Note: Edit this file to see the Markdown behind the examples.
52
53### Headers
54
Justin Wood0a9545e2020-04-20 18:15:21 -070055The document title should be an h1 header (#) and in title case (all words are
56capitalized). All section headers should be h2 (##) or lower and in sentence
57case (only the first word and proper nouns are capitalized).
Justin Woodc9bbb252020-03-03 10:03:58 -080058
Justin Wood0a9545e2020-04-20 18:15:21 -070059The best practice for document clarity is to not go lower than h3, but h4 is
60fine on occasion. Try to avoid using h4 often, or going lower than h4. If this
61happens, the document should be reorganized or broken up to ensure it stays at
62h3 with the occasional h4.
Justin Woodc9bbb252020-03-03 10:03:58 -080063
64### Command line examples
65
Justin Wood0a9545e2020-04-20 18:15:21 -070066Feel free to use either `$` or `%` to preface command line examples, but be
67consistent within the same doc or set of docs:
Justin Woodc9bbb252020-03-03 10:03:58 -080068
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
lzgrablic02a9f7b802021-12-16 03:24:03 -050076If you need to use a full terminal prompt with username and hostname, use the
Justin Wood0a9545e2020-04-20 18:15:21 -070077format of `root@{hostname}{special-characters}#`.
Justin Woodc9bbb252020-03-03 10:03:58 -080078
Justin Wood0a9545e2020-04-20 18:15:21 -070079For example, when logged into a Docker container, you might have a prompt like
80this:
81
Justin Woodc9bbb252020-03-03 10:03:58 -080082```
83root@c0f3912a74ff:/#
84```
85
Justin Woodc9bbb252020-03-03 10:03:58 -080086### Commands and output
87
88All example commands and output should be in code blocks with backticks:
89
90```
91code in backticks
92```
93
Justin Wood0a9545e2020-04-20 18:15:21 -070094...unless the code is within a step list. In a step list, indent the code
95blocks:
Justin Woodc9bbb252020-03-03 10:03:58 -080096
97 code indented
98
99### Code blocks in step lists
100
Justin Wood0a9545e2020-04-20 18:15:21 -0700101When writing procedures that feature code blocks, indent the content for the
102code blocks:
Justin Woodc9bbb252020-03-03 10:03:58 -0800103
Justin Wood0a9545e2020-04-20 18:15:21 -07001041. Step one:
Justin Woodc9bbb252020-03-03 10:03:58 -0800105
106 $ git clone https://github.com/project-chip/connectedhomeip.git
107 $ cd connectedhomeip
108
1091. Step two, do something else:
110
111 $ ./configure
112
Justin Wood0a9545e2020-04-20 18:15:21 -0700113For clarity in instructions, avoid putting additional step commands after a code
114sample within a step item. Instead rewrite the instruction so this is not
115necessary.
Justin Woodc9bbb252020-03-03 10:03:58 -0800116
117For example, avoid this:
118
1191. Step three, do this now:
120
121 $ ./configure
122
123 And then you will see that thing.
124
125Instead, do this:
126
1271. Step three, do this now, and you will see that thing:
128
Justin Wood0a9545e2020-04-20 18:15:21 -0700129 $ ./configure
Justin Woodc9bbb252020-03-03 10:03:58 -0800130
131### Inline code
132
Justin Wood0a9545e2020-04-20 18:15:21 -0700133Use backticks for `inline code`. This includes file paths and file or binary
134names.
Justin Woodc9bbb252020-03-03 10:03:58 -0800135
Pankaj Garg43c9c682020-03-20 15:06:18 -0700136### Code Comments
137
138Use uppercase `CHIP` in comments, as it is an acronym.
Justin Woodc9bbb252020-03-03 10:03:58 -0800139
Justin Woodc9bbb252020-03-03 10:03:58 -0800140Supported keywords:
141
Justin Wood0a9545e2020-04-20 18:15:21 -0700142| Keyword | Description |
143| ------- | ----------- |
144| alarm | Alarm |