|
| 1 | +# Documentation Guidelines |
| 2 | + |
| 3 | +## Authoring Guidelines |
| 4 | + |
| 5 | +We want our documentation to be easy to read and understand. This section describes guidelines for writing documentation that is clear, concise, confident, and courteous. |
| 6 | + |
| 7 | +For details on organizing content and how we use Markdown, refer to [Structure and Formatting](#structure-and-formatting-guidelines). |
| 8 | + |
| 9 | +### Use Simple English |
| 10 | + |
| 11 | +* **Be brief.** Use short sentences and paragraphs. Stick to the principle of one main idea per sentence, plus one additional point if needed. Each paragraph should address one main idea. Remember the basic structure of a paragraph: Introduction, body, and conclusion. |
| 12 | +* **Use simple words.** Use simple words to increase reader comprehension and reduce ambiguity. Follow our tips for making good word choices: |
| 13 | + * **Avoid jargon:** Write for your audience, using everyday language where possible, and technical terms where appropriate. Avoid clichés, idioms, and metaphors. |
| 14 | + * **Be consistent:** Use one term for each concept or action and use it consistently. |
| 15 | + * **Avoid “fancy” words and phrases:** If there is a simpler word or phrase, use it. |
| 16 | + |
| 17 | +### Make Content Scannable |
| 18 | + |
| 19 | +Organize your content to make it scannable for the reader, which helps them find what they need quickly, and to understand the information more efficiently. |
| 20 | + |
| 21 | +* **Put the most important content first.** Make sure your introduction clearly communicates what the reader can find on the page. Present the point of the document first, and organize supporting information towards the end of the page. |
| 22 | +* **Write scannable headings.** Expect readers of documentation to skim and scan the content, and to leave if they don’t find what they need quickly. Good headings add organization to your content and help the reader to find and understand content more effectively. Follow our guidelines for writing effective Headings. |
| 23 | +* **Write great link text.** Great link text tells the reader what they can expect when they click on a link. It also helps make the page more scannable. Follow our guidelines for writing Link text. |
| 24 | + |
| 25 | +### Use Strong Verbs |
| 26 | + |
| 27 | +* **Passive verbs make writing stuffy and formal**. Use strong verbs to get to the point and avoid unnecessary words and phrases. |
| 28 | +* **Commands**, also called imperatives, are the fastest and most direct way of giving someone instructions. |
| 29 | +* **Use simple present tense** instead of future tense for most text. Search for the words “will” or “shall” to find future tense instances. Future tense is acceptable for conditional statements, such as in a caution or a warning. |
| 30 | + |
| 31 | +### Parallelism |
| 32 | + |
| 33 | +Parallelism refers to the practice of using similar patterns of grammar, and sometimes length, to coordinate words, phrases, and clauses. |
| 34 | +Use parallel construction in lists. The table below shows some unparallel structures and how they can be made parallel with a little rewording. |
| 35 | + |
| 36 | +| Parallel (do) | Unparallel (don’t) | |
| 37 | +|-------------------------|---------------------------| |
| 38 | +| 1. Mount the panel. | 1. Mount the panel. | |
| 39 | +| 2. Install the battery. | 2. Battery installation. | |
| 40 | +| 3. Wire the keypad. | 3. Wiring the keypad. | |
| 41 | + |
| 42 | +## Structure Guidelines |
| 43 | + |
| 44 | +Content should be organized to support scanning. Consistent organization, formatting, and writing style helps readers quickly find what they need and to understand the content more effectively. This section describes our organization. |
| 45 | + |
| 46 | +### Website Structure |
| 47 | +The documentation website is organized this way: |
| 48 | + |
| 49 | +1. **Getting Started**: installation guides, prerequisites, how to set working environment |
| 50 | +2. **How To-s**: videos and guides, for some reason not included in **Guides** section |
| 51 | +3. **Guides**: developer guides for all OpenVINO Toolkit components |
| 52 | +4. **Resources**: samples, demos, pre-trained models and tools (Accuracy Checker, Post-Training Optimization etc) |
| 53 | +5. **Performance Information**: benchmark tests information, ways to improve Performance |
| 54 | +6. **API References**: in-built wiki with class structures |
| 55 | + |
| 56 | +### Page Structures |
| 57 | +Each page in the documentation should follow the basic format of: |
| 58 | + |
| 59 | +* **Overview**: 1-2 sentences describing what this page shows and why it matters |
| 60 | +* **Prerequisites**: Describe any pre-work necessary to the content (if appropriate) |
| 61 | +* **Content** |
| 62 | +* **Next steps**: List links to next steps (if appropriate) |
| 63 | +* **Related topics**: List links to related content (if appropriate) |
| 64 | + |
| 65 | +## Formatting Guidelines |
| 66 | +We apply the formatting using Markdown. |
| 67 | + |
| 68 | +### Inline Text Formatting |
| 69 | +Use our quick reference for the most commonly used inline text elements: |
| 70 | + |
| 71 | +| Element | Markdown Examples | Notes | |
| 72 | +|--------------- |---------------------| -------- | |
| 73 | +| Notes | `> **NOTE**: text` | The space between `>` and `**NOTE**` is required | |
| 74 | +| Code elements (variables, methods, classes) | ``` `text` ``` | | |
| 75 | +| Code snippets | ` ```cpp`<br>text<br>` ``` ` | | |
| 76 | +| Console commands, output| ` ```sh`<br>text<br>` ``` ` | | |
| 77 | +| Product name | OpenVINO™,<br>Intel® Distribution of OpenVINO™ toolkit | | |
| 78 | + |
| 79 | +### Headings |
| 80 | +Use headings to section and organize your content for better readability and clarity. |
| 81 | + |
| 82 | +* **Use strong verbs.** Strong, active verbs get to the point. Avoid **-ing** verbs, such as Running, Testing, etc. |
| 83 | +* **Be concise and descriptive.** Use only the words necessary to describe the section. |
| 84 | +* **Use sentence case.** Capitalize first letter every word except articles, prepositions: **Build Inference Engine on Linux** |
| 85 | +* **Avoid punctuation.** Unless your heading is a question, don’t use sentence punctuation in headings. |
| 86 | +* **Use parallel structure.** Headings at the same level should use the same grammatical pattern. This provides structure to the document and helps users find information more easily. See [Parallelism](#parallelism). |
| 87 | + |
| 88 | +Use following rules to write headings in your documentation: |
| 89 | +* All files must have a top level heading, which is the title for the page. |
| 90 | + ``` |
| 91 | + # First Level Heading |
| 92 | + ``` |
| 93 | +* Up to three additional levels of headings are allowed under the title heading. |
| 94 | + ``` |
| 95 | + ## Second Level Heading |
| 96 | + ### Third Level Heading |
| 97 | + #### Fourth Level Heading |
| 98 | + ``` |
| 99 | +* Each heading should be followed by at least one paragraph of content. Avoid two or more consecutive headings. |
| 100 | +* To add a link to a heading in the current page, do the following: |
| 101 | + * Add the `<a>` HTML tag and set a unique name to your heading with `name` argument: |
| 102 | + ```XML |
| 103 | + ## <a name="set-the-environment-variables"></a> Set the Environment Variables |
| 104 | + ``` |
| 105 | + * Place the link to the heading using the set name: |
| 106 | + ```XML |
| 107 | + Refer <a href="#set-the-environment-variables">here</a> |
| 108 | + ``` |
| 109 | + |
| 110 | +### Code Snippets and Examples |
| 111 | +You can create fenced code snippets by placing triple backticks ` ``` ` before and after the code block and add an optional language identifier to enable syntax highlighting in your fenced code block. For example, to syntax highlight C++ code: |
| 112 | +``` |
| 113 | +```cpp |
| 114 | +#include <inference_engine.hpp> |
| 115 | +void main(int argc, char *argv[]) |
| 116 | +{ |
| 117 | + InferenceEngine::Core ie; |
| 118 | +} |
| 119 | +``` |
| 120 | +
|
| 121 | +```cpp |
| 122 | +#include <inference_engine.hpp> |
| 123 | +void main(int argc, char *argv[]) |
| 124 | +{ |
| 125 | + InferenceEngine::Core ie; |
| 126 | +} |
| 127 | +``` |
| 128 | + |
| 129 | +For full list with supported languages refer [here](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). |
| 130 | + |
| 131 | +### Lists and Instructions |
| 132 | +This section provides information about formatting numbered and bulleted lists. |
| 133 | + |
| 134 | +#### Numbered Lists |
| 135 | +Use a numbered list when the order or priority of the items is important, such as step-by-step instructions: |
| 136 | +``` |
| 137 | +1. **Initialize core** to.. |
| 138 | +2. **Prepare input** for.. |
| 139 | +3. ... |
| 140 | +``` |
| 141 | +Numbered lists are most frequently used for procedures. Use numbered lists to show sequence for the items. Follow our guidelines for numbered lists: |
| 142 | +* Make few first words describe whole step and bold it: |
| 143 | + 6) **Prepare input**. You can use one of the following options to prepare input |
| 144 | +* Introduce a numbered list with a sentence. End the setup text with a colon. Example: |
| 145 | + "To configure the unit, perform the following steps:" |
| 146 | +* Each item in the list should be [parallel](#parallelism). |
| 147 | +* Treat numbered list items as full sentences with correct ending punctuation. |
| 148 | +* You may interrupt numbered lists with other content, if relevant, e.g. explanatory text, commands, or code. |
| 149 | + |
| 150 | +#### Bulleted lists |
| 151 | +Use a bulleted list when the order of the items is not important: |
| 152 | +``` |
| 153 | +* Option X |
| 154 | +* Option Y |
| 155 | +* Option Z |
| 156 | +``` |
| 157 | +* Introduce a bulleted list with a sentence. End the setup text with a colon. Example: |
| 158 | + “To repair the unit, you will need the following items:” |
| 159 | +* Make few first words describe whole step and bold it: |
| 160 | + * **Prepare input**. You can use one of the following options to prepare input |
| 161 | +* Each item in the list should be parallel. |
| 162 | +* Avoid interrupting bulleted lists with other paragraph styles. |
| 163 | +* Second-level bullets are acceptable; avoid third-level bullets. |
| 164 | + |
| 165 | +For both list types, keep all items in the list parallel. See [Parallelism](#parallelism): |
| 166 | + |
| 167 | +### Links |
| 168 | +All links in content should follow these guidelines: |
| 169 | + |
| 170 | +* **Avoid generic text:** Don’t use generic, uninformative link text such as “click here” or “read more”. |
| 171 | +* **Write descriptive link text:** Link text should describe where the link goes, without having to read the surrounding text. |
| 172 | +* **Use unique link text:** Each link text on a page should be unique. If users see the same link text twice on a page, they’ll assume it goes to the same place. |
| 173 | +* **Start link text with keywords:** Frontload the link text with the most important words to help users scan the text. |
| 174 | + |
| 175 | +Use following examples to write links in your documentation: |
| 176 | +* To add a cross-reference to another documentation page, use file path from [DoxygenLayout.xml](./openvino-documentation/blob/master/docs/doxygen/DoxygenLayout.xml) (don't use direct links to docs.openvinotoolkit.org): |
| 177 | +``` |
| 178 | +[OpenVINO Installation on Linux](./docs/install_guides/installing-openvino-linux.md) |
| 179 | +``` |
| 180 | +Currently links to headings in other markdown files are not supported. To refer to a specific section, you may use the following example: |
| 181 | +``` |
| 182 | +"Use **Set Environment Variables** section in the [OpenVINO Installation on Linux](./docs/install_guides/installing-openvino-linux.md) document. |
| 183 | +``` |
| 184 | +* To add URL link to any software, link to the latest version, for example: |
| 185 | +``` |
| 186 | +For more details, see [CMake page](https://cmake.org/cmake/help/latest/manual/cmake.1.html#manual:cmake(1)) |
| 187 | +``` |
| 188 | + |
| 189 | +## Graphics Guidelines |
| 190 | +Use images or figures to convey information that may be difficult to explain using words alone. Well-planned graphics reduce the amount of text required to explain a topic or example. |
| 191 | + |
| 192 | +Follow these guidelines when using graphics in support of your documentation: |
| 193 | + |
| 194 | +* Keep it simple. Use images that serve a specific purpose in your document, and contain only the information the reader needs. |
| 195 | +* Avoid graphics that will need frequent updating. Don’t include information in a graphic that might change with each release, such as product versions. |
| 196 | +* Use either PNG or JPEG bitmap files for screenshots and SVG files for vector graphics. |
| 197 | +* Place the image immediately after the text it helps clarify, or as close as possible. |
| 198 | +* Use the Markdown directives to insert images and figures into the document. Include both alt text, and the title. |
| 199 | +* Include at least one direct reference to an image from the main text, using the figure number. |
| 200 | + |
| 201 | +Images should follow these naming and location conventions: |
| 202 | + |
| 203 | +* Save the image files in a figures folder at the same level as the file that will reference the image. |
| 204 | +* Name image files according to the following rules: |
| 205 | + * Use only lower case letters. |
| 206 | + * Separate multiple words in filenames using dashes. |
| 207 | + * Name images using the filename of the file they appear on and add a number to indicate their place in the file. For example, the third figure added to the `welcome.md` file must be named `welcome-3.png`. |
0 commit comments