|
| 1 | +--- |
| 2 | +applyTo: '**/*.md' |
| 3 | +--- |
| 4 | +# Documentation Writing Instructions |
| 5 | + |
| 6 | +These are our documentation writing style guidelines. |
| 7 | + |
| 8 | +## General Style tips |
| 9 | + |
| 10 | +* Get to the point fast. |
| 11 | +* Talk like a person. |
| 12 | +* Simpler is better. |
| 13 | +* Be brief. Give customers just enough information to make decisions confidently. Prune every excess word. |
| 14 | +* We use Hugo to generate our docs. |
| 15 | + |
| 16 | +## Grammar |
| 17 | + |
| 18 | +* Use present tense verbs (is, open) instead of past tense (was, opened). |
| 19 | +* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would". |
| 20 | +* Use active voice where the subject performs the action. |
| 21 | +* Write in second person (you) to speak directly to readers. |
| 22 | +* Use gender-neutral language. |
| 23 | +* Avoid multiple -ing words that can create ambiguity. |
| 24 | +* Keep prepositional phrases simple and clear. |
| 25 | +* Place modifiers close to what they modify. |
| 26 | + |
| 27 | +## Capitalization |
| 28 | + |
| 29 | +* Use sentence-style capitalization for everything except proper nouns. |
| 30 | +* Always capitalize proper nouns. |
| 31 | +* Don’t capitalize the spelled-out form of an acronym unless it's a proper noun. |
| 32 | +* In programming languages, follow the traditional capitalization of keywords and other special terms. |
| 33 | +* Don't use all uppercase for emphasis. |
| 34 | + |
| 35 | +## Numbers |
| 36 | + |
| 37 | +* Spell out numbers for zero through nine, unless space is limited. Use numerals for 10 and above. |
| 38 | +* Spell out numbers at the beginning of a sentence. |
| 39 | +* Spell out ordinal numbers such as first, second, and third. Don't add -ly to form adverbs from ordinal numbers. |
| 40 | + |
| 41 | +## Punctuation |
| 42 | + |
| 43 | +* Use short, simple sentences. |
| 44 | +* End all sentences with a period. |
| 45 | +* Use one space after punctuation marks. |
| 46 | +* After a colon, capitalize only proper nouns. |
| 47 | +* Avoid semicolons - use separate sentences instead. |
| 48 | +* Use question marks sparingly. |
| 49 | +* Don't use slashes (/) - use "or" instead. |
| 50 | + |
| 51 | +## Text formatting |
| 52 | + |
| 53 | +* UI elements, like menu items, dialog names, and names of text boxes, should be in bold text. |
| 54 | +* Use code style for: |
| 55 | + * Code elements, like method names, property names, and language keywords. |
| 56 | + * SQL commands. |
| 57 | + * Command-line commands. |
| 58 | + * Database table and column names. |
| 59 | + * Resource names (like virtual machine names) that shouldn't be localized. |
| 60 | + * URLs that you don't want to be selectable. |
| 61 | +* For code placeholders, if you want users to replace part of an input string with their own values, use angle brackets (less than < and greater than > characters) on that placeholder text. |
| 62 | +* Don't apply an inline style like italic, bold, or inline code style to headings. |
| 63 | + |
| 64 | +## Alerts |
| 65 | + |
| 66 | +* Alerts are a Markdown extension to create block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported: |
| 67 | + |
| 68 | + * `[!NOTE]` Information the user should notice even if skimming. |
| 69 | + * `[!TIP]` Optional information to help a user be more successful. |
| 70 | + * `[!IMPORTANT]` Essential information required for user success. |
| 71 | + * `[!CAUTION]` Negative potential consequences of an action. |
| 72 | + * `[!WARNING]` Dangerous certain consequences of an action. |
| 73 | + |
| 74 | +## Links |
| 75 | + |
| 76 | +* Links to other documentation articles should be relative, not absolute. Include the `.md` suffix. |
| 77 | +* Links to bookmarks within the same article should be relative and start with `#`. |
| 78 | +* Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here". |
| 79 | + |
| 80 | +## Images |
| 81 | + |
| 82 | +* Use images only when they add value. |
| 83 | +* Images have a descriptive and meaningful alt text that starts with "Screenshot showing" and ends with ".". |
| 84 | +* Videos have a descriptive and meaningful alt text or title that starts with "Video showing" and ends with ".". |
| 85 | + |
| 86 | +## Numbered steps |
| 87 | + |
| 88 | +* Write complete sentences with capitalization and periods |
| 89 | +* Use imperative verbs |
| 90 | +* Clearly indicate where actions take place (UI location) |
| 91 | +* For single steps, use a bullet instead of a number |
| 92 | +* When allowed, use angle brackets for menu sequences (File > Open) |
| 93 | +* When writing ordered lists, only use 1's. |
| 94 | + |
| 95 | +## Terminology |
| 96 | + |
| 97 | +* Use "Select" instead of "Click" for UI elements like buttons, menu items, links, dropdowns, and checkboxes. |
| 98 | +* Use "might" instead of "may" for conditional statements. |
| 99 | +* Avoid latin abbreviations like "e.g.". Use "for example" instead. |
| 100 | +* Use the verb "to enable" instead "to allow" unless you're referring to permissions. |
| 101 | +* Follow the terms and capitalization guidelines in #fetch [VS Code docs wiki](https://github.com/microsoft/vscode-docs/wiki/VS-Code-glossary) |
| 102 | + |
| 103 | + |
| 104 | +## Complete style guide |
| 105 | + |
| 106 | +Find all the details of the style guide in these files: |
| 107 | + |
| 108 | +- `./content/contribute/style/grammar.md` – Grammar rules |
| 109 | +- `./content/contribute/style/formatting.md` – Formatting rules |
| 110 | +- `./content/contribute/style/recommended-words.md` – Approved words and phrasing |
| 111 | +- `./content/contribute/style/voice-tone.md` – Voice and tone guidance |
0 commit comments