github.com/pachyderm/pachyderm@v1.13.4/doc/docs/1.10.x/contributing/docs-style-guide.md (about) 1 # Pachyderm Technical Documentation Style Guide 2 3 This document provides main guidelines for creating technical content 4 that describes Pachyderm concepts and operations. This style guide is 5 based on Google Developer Documentation Style Guide and serves as a quick 6 reference for everyone who wants to contribute to the Pachyderm documentation. 7 For a more detailed overview, see the [Google Developer Documentation 8 Style Guide](https://developers.google.com/style/). 9 10 ## Overview 11 12 We welcome all contributions to the Pachyderm technical documentation and are 13 happy to help incorporate your content into our docs! We hope that this 14 document will assits in answering some of your questions about our 15 contributing guidelines. 16 17 ## Writing Style 18 19 Friendly but not overly colloquial. Avoid jargon, idioms, and references 20 to pop culture. Use shorter sentences and words over longer alternatives. 21 22 Things to avoid: 23 24 * "Please" and "thank you". 25 * Exclamation marks. 26 * Announcement of features that have not yet been developed. 27 * All caps to emphasize the importance. 28 * Parenthesis as much as possible. Use commas instead. 29 30 | Do not use | Use | 31 | ---------- | --- | 32 | We'll walk you through the installation of the product X. It might be a bit difficult, but don't worry, we are here to help. | This guide walks you through the process of installation of the product X. | 33 34 ## Write in the present tense and in second person 35 36 Say "you" instead of "we" and use the present tense where possible. Only use 37 the future tense when talking about the events that will not happen immediately 38 but sometime in the future. The future tense introduces uncertainty about 39 when an action takes places. Therefore, in most cases, use the present tense. 40 41 | Do not use | Use | 42 | ---------- | --- | 43 | We are going to create a new configuration file that will describe our deployment. | To create a new configuration file that describes our deployment, complete the following steps. | 44 45 ## Write for an international audience 46 47 Avoid idioms and jargon and write in simple American English. The content 48 that you are writing might later be translated into other foreign languages. 49 Translating simple short phrases is much easier than long sentences. Use 50 consistent terminology and avoid misplacing modifiers. Spell out abbreviations 51 on the first occurrence. 52 53 | Do not use | Use | 54 | ---------- | --- | 55 | After completing these steps, you are off to the races! | After you complete these steps, you can start using Pachyderm. | 56 57 ## Write in Active Voice 58 59 Sentences written in active voice are easier for the reader to understand. 60 A well-written text has about 95% of sentences written in active voice. 61 Use passive voice only when the performer of the action is unknown or 62 to avoid blaming the user for an error. 63 64 | Do not use | Use | 65 | ---------- | --- | 66 | This behavior means that `transform.err_cmd` can be used to ignore failed datums. | You can use `transform.err_cmd` to ignore failed datums. | 67 68 ## Put the Condition Before the Steps 69 70 If your sentence has a condition, start the sentence with the conditional 71 clause and add the descriptive instructions after the clause. 72 73 | Do not use | Use | 74 | ---------- | --- | 75 | See the Spark documentation for more information. | For more information, see the Spark documentation. | 76 77 ## Use Numbered Lists for a Sequence of Steps 78 79 If the user needs to follow a set of instructions, organize them in a 80 numbered list rather than in a bulleted list. Options can be described in a 81 bulleted list. An exception to this rule is when you have just one step. 82 83 | Do not use | Use | 84 | ---------- | --- | 85 | * Create a configuration and run the following command. | 1. Create a configuration file. <br> 2. Run the following command: | 86 87 ## Break Your Content Into Smaller Chunks 88 89 Users do not read the whole body of the text. Instead, they skip and 90 scan through looking for the text structures that stand out, such as 91 headings, numbered and bulleted lists, tables, and so on. Try to structure 92 your content so that it is easy to scan through by adding more titles, 93 organizing instructions in sequences of steps, and adding tables and 94 lists for properties and descriptions. 95 96 Avoid Ending a Sentence with a Preposition 97 98 Phrasal verbs are a little bit less formal than single-word verbs. If 99 possible, replace a phrasal word with a single-word verb equivalent and 100 if you have to use a phrasal word, avoid finishing the sentence with 101 a preposition. 102 103 | Do not use | Use | 104 | ---------- | --- | 105 | The `put file` API includes an option for splitting **up** the file into separate datums automatically. | The `put file` API includes an option for splitting the file into separate datums automatically. | 106 107 ##Use meaningful links 108 109 Link text should mean something to the users when they read it. Phrases 110 like **Click here** and **Read more** do not provide useful information. 111 They might be good for call-to-action (CA) buttons on the marketing part 112 of the website, but in technical content they introduce uncertainty and 113 confusion. 114 115 Furthermore, if a user generates a list of links or uses a speech recognition 116 technology to navigate through the page, they use keywords and phrases, 117 such as "Click <text>". Generic links are not helpful for them. 118 119 Also, use a standard phrase *For more information, see <link>* to 120 introduce a link. 121 122 | Do not use | Use | 123 | ---------- | --- | 124 | More information about getting your FREE trial token and activating the dashboard can be found [here](https://docs.pachyderm.com/latest/enterprise/deployment/#activate-by-using-the-dashboard). | For more information, see [Activate your token by using the dashboard](https://docs.pachyderm.com/latest/enterprise/deployment/#activate-by-using-the-dashboard). | 125 126 ## Markdown 127 128 The Pachyderm documentation uses Python Markdown, and many [PyMdown 129 Extensions](https://facelessuser.github.io/pymdown-extensions/) are supported. 130 See the `mkdocs.yaml` file for the list of supported 131 extensions. 132 133 In general, follow these guidelines: 134 135 * Do not use the admonitions in numbered lists because they break the order 136 and Markdown does not support starting lists from an arbitrary number. 137 138 * Enclose code blocks in "```" and specify the correct highlighting. 139 140 * While PyMdown Extensions provide advanced UI features, use them sparingly because not all browsers fully support all of them. 141 142 * Do not use the dollar sign `$` in code snippets. While the dollar sign 143 signifies the beginning of a line, it creates usability issues. When users 144 copy commands from a code block, they copy everything from that code 145 block, including the dollar sign. Then, they need to navigate to the 146 begining of the command prompt to remove the dollar sign, which is quite annoying. 147 Most of the commands that are described in the Pachyderm documentation 148 are run from a UNIX shell as a normal user. 149 150 ## Preview the Documentation Locally 151 152 The documentation for each version is stored in eponymous folders. Each 153 version uses its own configuration file that has a suffix named after 154 the corresponding version. 155 156 To serve the documentation locally, you need to run the `mkdocs serve` 157 command with the corresponding configuration file from the `docs` 158 folder. 159 160 For example, to build the master version of documentation, run: 161 162 ```shell 163 mkdocs serve -f mkdocs-master.yml 164 ``` 165 166 167 I hope you'll have fun with Python Markdown! :smile: