# Documentation style guide This style guide provides general guidance to anyone who contributes to Finboot end-user documentation. ## Our preferred style guide We have adopted the Google developer documentation style guide for our documentation, which you can use for anything not covered here. For a quick summary, see the [Google style guide highlights](https://developers.google.com/style/highlights). The rest of this document hightlights the most important recommendations and describes our project-specific customizations to Google's guide. ## Templates This project recommends using the following templates from the [Good Docs project](https://github.com/thegooddocsproject/templates): - Quickstart - Explanation - Tutorial ## General writing tips ### Put yourself in your audience's shoes Know who you are writing for. Is it for a teammate? Is it for another developer who wants to extend the product? Or is it for an end-user? Knowing your audience helps you decide what information you should include, how many details you should add, and how you should organize it. ### Be friendly but do not overdo it You can be conversational but please do not crack a joke in every paragraph. It is all about balance. Your sweet spot will be right between being formal and talking to a friend. ### Start every page with a short introduction Let the reader know about the topic, key points and purpose of the following instructions. By adding an introduction, your writing becomes more accessible. ### Write for a global audience When contributing to this project, you should strive to write documentation with inclusivity and diversity in mind. Inclusive language recognizes diversity and strives to communicate respectfully to all people. This kind of language is sensitive to differences and seeks to promote equal opportunities. For resources on making your writing more inclusive, see [Inclusive documentation](https://developers.google.com/style/inclusive-documentation). ### Write short sentences Long sentences make your text hard to follow. Break up long sentences into two or more lines and remove redundant or fluff words such as "simply" or "just". ### Write in the second person (you) rather than in the first (we) or third person (users) The second person will help ensure clarity, especially when listing steps in a process. In second person your writing offers simple, concise instructions addressed directly to the reader. Exceptions: Personal recommendation (For example We recommend ...") ### Use present tense The present tense makes your writing simpler and more direct. Conditional or future tense overcomplicates your instructions. For example "Modify the file." instead of "You will modify the file." ### Use active voice when possible Active voice keeps your sentences from becoming too wordy and complicated. Passive voice can cloud the meaning so it is best to avoid it. For example "Remove the link." instead of "The link needs to be removed." ### Use British spelling and punctuation Our project uses British spelling and punctuation. ### Put conditional clauses before instructions If you start with the conditional clause, the reader will immediately grasp the information. This will lead to a much quicker understanding of your instructions. For example "For more examples, see X" instead of "See X for more examples". ### Use descriptive link text. Links need to make sense on their own. Link texts should be phrases that describe what the reader will find on the destination page or they should be exact article titles. Instead of "For more details, click here." it is best to use "For more details, see article name". ### Eliminate contractions Contractions make your writing more informal. Try to avoid them entirely. E.g. “What is” instead of “What’s” or “It is” instead of “It’s”. ## Formatting ### Use sentence case for document titles and section headings Capitalize only the first word and any proper nouns. For example "How to create a JavaScript file". If it's a title of a guide, we prefer to start with the infinitive form of the verb. For example "Create a new file" instead of "How to create a new file" or "Creating a new file". ### Use numbered lists for step-by-step instructions For example: 1. Step 1 (For example "Create a new…") 2. Step 2 (For example "Copy the contents from …") 3. Step 3 (For example "Edit …") ### Use bulleted lists for most other lists For example: * Prerequisite 1 * Prerequisite 2 * Prerequisite 3 ### Use code font for functions and class names, variables, values, code snippets, and file names If you write the name of a function, file, class, or variable (anything that is code related) use backticks so it will be shown in code font. For example: `file.txt` `function()` `MyClass` ` var myVariable` `` ### Put UI elements in bold UI (User Interface) elements can be names for buttons, list items, menus, dialogs, or any other feature. Put these elements in bold. For example: "Click on the **Create** button" or "Go to the left menu and click on **Options**." ### Limit the use of italics and underlined text Try to keep your formatting minimalistic and clean. If you want to highlight a part of your documentation you can use lists or amonitions (For example "Important:" or "Note:"). Only use italics if you are quoting someone. ## Visual content Visual content will help you to make your writing easy-to-interpret. To ensure that your images are actually improving your documentation, follow these guidelines. * **Be relevant:** Images are expensive to maintain. Keep in mind what the goal of your documentation is and only use images that will help the user to understand the content better. For example, think twice before adding any screenshots since the UI could change. * **Have the right size:** For example, a screenshot should neither communicate too much information nor too little. * **Use design elements to highlight important aspects:** For example add readable colors or numbers to show a sequence. * **Do not expose sensitive information:** Remove any name, username, email, and avatar from images. ## Glossary of preferred terms The table provides guidelines about the terms you should and should not use for consistency, listed in alphabetical order: Preferred Term | Avoid These Terms | Explanation --------------- | ----------------- | ----------- Finboot | finboot, FINBOOT | Brand name. MARCO | marco, Marco | Brand name. SDK | Sdk, SDK | Acronym. API | Api, api | API. Console | console, CONSOLE | Brand name, only when refering to MARCO console.