strong-tie/inbound-calls

1# Fastify Style Guide2 3## Welcome4 5Welcome to *Fastify Style Guide*. This guide is here to provide you with a6conventional writing style for users writing developer documentation on our Open7Source framework. Each topic is precise and well explained to help you write8documentation users can easily understand and implement.9 10## Who is this guide for?11 12This guide is for anyone who loves to build with Fastify or wants to contribute13to our documentation. You do not need to be an expert in writing technical14documentation. This guide is here to help you.15 16Visit the [contribute](https://fastify.dev/contribute) page on our website or17read the18[CONTRIBUTING.md](https://github.com/fastify/fastify/blob/main/CONTRIBUTING.md)19file on GitHub to join our Open Source folks.20 21## Before you write22 23You need to know the following:24 25* JavaScript26* Node.js27* Git28* GitHub29* Markdown30* HTTP31* NPM32 33### Consider your Audience34 35Before you start writing, think about your audience. In this case, your audience36should already know HTTP, JavaScript, NPM, and Node.js. It is necessary to keep37your readers in mind because they are the ones consuming your content. You want38to give as much useful information as possible. Consider the vital things they39need to know and how they can understand them. Use words and references that40readers can relate to easily. Ask for feedback from the community, it can help41you write better documentation that focuses on the user and what you want to42achieve.43 44### Get straight to the point45 46Give your readers a clear and precise action to take. Start with what is most47important. This way, you can help them find what they need faster. Mostly,48readers tend to read the first content on a page, and many will not scroll49further.50 51**Example**52 53Less like this: Colons are very important to register a parametric path. It lets54the framework know there is a new parameter created. You can place the colon55before the parameter name so the parametric path can be created.56 57More Like this: To register a parametric path, put a colon before the parameter58name. Using a colon lets the framework know it is a parametric path and not a59static path.60 61### Avoid adding video or image content62 63 64Do not add videos or screenshots to the documentation. It is easier to keep65under version control. Videos and images will eventually end up becoming66outdated as new updates keep developing. Instead, make a referral link or a67YouTube video. You can add links by using `[Title](www.websitename.com)` in the68markdown.69 70**Example**71 72```73To learn more about hooks, see [Fastify hooks](https://fastify.dev/docs/latest/Reference/Hooks/).74```75 76Result:77>To learn more about hooks, see [Fastify78>hooks](https://fastify.dev/docs/latest/Reference/Hooks/).79 80 81 82### Avoid plagiarism83 84Make sure you avoid copying other people's work. Keep it as original as85possible. You can learn from what they have done and reference where it is from86if you used a particular quote from their work.87 88 89## Word Choice90 91There are a few things you need to use and avoid when writing your documentation92to improve readability for readers and make documentation neat, direct, and93clean.94 95 96### When to use the second person "you" as the pronoun97 98When writing articles or guides, your content should communicate directly to99readers in the second person ("you") addressed form. It is easier to give them100direct instruction on what to do on a particular topic. To see an example, visit101the [Plugins Guide](./Plugins-Guide.md).102 103**Example**104 105Less like this: we can use the following plugins.106 107More like this: You can use the following plugins.108 109> According to [Wikipedia](#), ***You*** is usually a second person pronoun.110> Also, used to refer to an indeterminate person, as a more common alternative111> to a very formal indefinite pronoun.112 113## When to avoid the second person "you" as the pronoun114 115One of the main rules of formal writing such as reference documentation, or API116documentation, is to avoid the second person ("you") or directly addressing the117reader.118 119**Example**120 121Less like this: You can use the following recommendation as an example.122 123More like this: As an example, the following recommendations should be124referenced.125 126To view a live example, refer to the [Decorators](../Reference/Decorators.md)127reference document.128 129 130### Avoid using contractions131 132Contractions are the shortened version of written and spoken forms of a word,133i.e. using "don't" instead of "do not". Avoid contractions to provide a more134formal tone.135 136### Avoid using condescending terms137 138Condescending terms are words that include:139 140* Just141* Easy142* Simply143* Basically144* Obviously145 146The reader may not find it easy to use Fastify's framework and plugins; avoid147words that make it sound simple, easy, offensive, or insensitive. Not everyone148who reads the documentation has the same level of understanding.149 150 151### Starting with a verb152 153Mostly start your description with a verb, which makes it simple and precise for154the reader to follow. Prefer using present tense because it is easier to read155and understand than the past or future tense.156 157**Example**158 159 Less like this: There is a need for Node.js to be installed before you can be160 able to use Fastify.161 162 More like this: Install Node.js to make use of Fastify.163 164### Grammatical moods165 166Grammatical moods are a great way to express your writing. Avoid sounding too167bossy while making a direct statement. Know when to switch between indicative,168imperative, and subjunctive moods.169 170 171**Indicative** - Use when making a factual statement or question.172 173Example: Since there is no testing framework available, "Fastify recommends ways174to write tests".175 176**Imperative** - Use when giving instructions, actions, commands, or when you177write your headings.178 179Example: Install dependencies before starting development.180 181 182**Subjunctive** -  Use when making suggestions, hypotheses, or non-factual183statements.184 185Example: Reading the documentation on our website is recommended to get186comprehensive knowledge of the framework.187 188### Use **active** voice instead of **passive**189 190Using active voice is a more compact and direct way of conveying your191documentation.192 193**Example**194 195 196Passive: The node dependencies and packages are installed by npm.197 198Active:  npm installs packages and node dependencies.199 200## Writing Style201 202### Documentation titles203 204When creating a new guide, API, or reference in the `/docs/` directory, use205short titles that best describe the topic of your documentation. Name your files206in kebab-cases and avoid Raw or camelCase. To learn more about kebab-case you207can visit this medium article on [Case208Styles](https://medium.com/better-programming/string-case-styles-camel-pascal-snake-and-kebab-case-981407998841).209 210**Examples**:211 212>`hook-and-plugins.md`,213 214 `adding-test-plugins.md`,215 216 `removing-requests.md`.217 218### Hyperlinks219 220Hyperlinks should have a clear title of what it references. Here is how your221hyperlink should look:222 223```MD224<!-- More like this -->225 226// Add clear & brief description227[Fastify Plugins] (https://fastify.dev/docs/latest/Plugins/)228 229<!--Less like this -->230 231// incomplete description232[Fastify] (https://fastify.dev/docs/latest/Plugins/)233 234// Adding title in link brackets235[](https://fastify.dev/docs/latest/Plugins/ "fastify plugin")236 237// Empty title238[](https://fastify.dev/docs/latest/Plugins/)239 240// Adding links localhost URLs instead of using code strings (``)241[http://localhost:3000/](http://localhost:3000/)242 243```244 245Include in your documentation as many essential references as possible, but246avoid having numerous links when writing for beginners to avoid distractions.247