docs/STYLE_GUIDE.md

   1 # CHIP Documentation Style Guide
   2
   3 CHIP documentation lives here:
   4
   5 -   **GitHub** — All guides and tutorials across the complete
   6     [Project-CHIP organization](https://github.com/project-chip).
   7
   8 See
   9 [CONTRIBUTING.md](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md)
  10 for general information on contributing to this project.
  11
  12 ## Location
  13
  14 Place all documentation contributions in the appropriate location in the
  15 [`/docs`](../docs) directory. Most contributions should go into the
  16 `/docs/guides` subdirectory, which covers conceptual and usage content.
  17
  18 Current documentation structure:
  19
  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                                                         |
  25 | `/docs/guides/profiles` | Content describing or illustrating use of CHIP profiles                                      |
  26 | `/docs/guides/test`     | Content related to testing CHIP                                                              |
  27 | `/docs/guides/tools`    | Content describing or illustrating use of CHIP tools                                         |
  28 | `/docs/guides/primer`   | CHIP Primer content                                                                          |
  29 | `/docs/presentations`   | PDF presentations on CHIP features                                                           |
  30 | `/docs/specs`           | PDFs of CHIP specifications                                                                  |
  31 | `/images`               | Top-level CHIP images, such as logos                                                         |
  32
  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.
  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
  46 > For more information, see the [CHIP Style Guide](./STYLE_GUIDE.md).
  47
  48 ## Markdown guidelines
  49
  50 Use standard Markdown when authoring CHIP documentation. While HTML may be used
  51 for more complex content such as tables, use Markdown as much as possible.
  52
  53 > Note: Edit this file to see the Markdown behind the examples.
  54
  55 ### Headers
  56
  57 The document title should be an h1 header (#) and in title case (all words are
  58 capitalized). All section headers should be h2 (##) or lower and in sentence
  59 case (only the first word and proper nouns are capitalized).
  60
  61 The best practice for document clarity is to not go lower than h3, but h4 is
  62 fine on occasion. Try to avoid using h4 often, or going lower than h4. If this
  63 happens, the document should be reorganized or broken up to ensure it stays at
  64 h3 with the occasional h4.
  65
  66 ### Command line examples
  67
  68 Feel free to use either `$` or `%` to preface command line examples, but be
  69 consistent within the same doc or set of docs:
  70
  71 ```
  72 $ git clone https://github.com/project-chip/connectedhomeip.git
  73 % git clone https://github.com/project-chip/connectedhomeip.git
  74 ```
  75
  76 ### Terminal prompts
  77
  78 If you need use a full terminal prompt with username and hostname, use the
  79 format of `root@{hostname}{special-characters}#`.
  80
  81 For example, when logged into a Docker container, you might have a prompt like
  82 this:
  83
  84 ```
  85 root@c0f3912a74ff:/#
  86 ```
  87
  88 ### Commands and output
  89
  90 All example commands and output should be in code blocks with backticks:
  91
  92 ```
  93 code in backticks
  94 ```
  95
  96 ...unless the code is within a step list. In a step list, indent the code
  97 blocks:
  98
  99     code indented
 100
 101 ### Code blocks in step lists
 102
 103 When writing procedures that feature code blocks, indent the content for the
 104 code blocks:
 105
 106 1.  Step one:
 107
 108         $ git clone https://github.com/project-chip/connectedhomeip.git
 109         $ cd connectedhomeip
 110
 111 1.  Step two, do something else:
 112
 113         $ ./configure
 114
 115 For clarity in instructions, avoid putting additional step commands after a code
 116 sample within a step item. Instead rewrite the instruction so this is not
 117 necessary.
 118
 119 For example, avoid this:
 120
 121 1.  Step three, do this now:
 122
 123         $ ./configure
 124
 125     And then you will see that thing.
 126
 127 Instead, do this:
 128
 129 1.  Step three, do this now, and you will see that thing:
 130
 131         $ ./configure
 132
 133 ### Inline code
 134
 135 Use backticks for `inline code`. This includes file paths and file or binary
 136 names.
 137
 138 ### Code Comments
 139
 140 Use uppercase `CHIP` in comments, as it is an acronym.
 141
 142 Supported keywords:
 143
 144 | Keyword | Description |
 145 | ------- | ----------- |
 146 | alarm   | Alarm       |