Project:
A Technical Style Guide
for Internal Documentation
Language & Grammar
Concise and accurate, but still accessible.
[In this introduction, add the company’s goals for the language section. Some companies want to link out to a more extensive source, while others have specific rules for their company. Included below are several standard sections with examples under each. See additional open-source examples included in the resources if you need ideas.]
Tone and Voice
Tone
Tone is the mood or attitude of a written piece. It can feel professional, informative, serious, sarcastic, humorous, or any other emotion.
The tone of internal writing for [Company name] should be [specific based on company or team needs].
- Use clear, concise writing. [see the linked Resource on how to find wordy phrases]
- Avoid personal opinions or subjective language.
One last note. Try to avoid colloquial or casual language, which can make it harder for non-native English speakers to understand. See the [section on non-native English Speakers] for more information.
Voice
Voice is the “sound” of the writing or how it feels to the reader. It can be formal, casual, or anything in between, but it should be consistent throughout the writing.
These are general recommendations and should always be balanced against [company]’s goal for internal documents:
- Use active voice; it’s more direct and concise.
In the active voice, the subject of the sentence is performing the action.
Example: “The user clicks the button to submit the form.” - Use Imperative sentences sparingly because they can feel too impersonal.
Example: “Click the button to submit the form.” - Avoid personal pronouns like “I,” “you,” or “we” to help the writing sound more objective and neutral.
[Some companies prefer a more informal style, which would allow for “you” or “we,” especially in the documentation for things like onboarding] - Use the third person point of view, using words like “he,” “she,” and “they” to refer to the reader or user. This can help to create a sense of distance and objectivity.
[Avoid using ‘he’ and ‘she’ in favor of some of the above options if the Style Guide needs to be gender-neutral.]
Overall, the most important thing is to choose a voice that is clear, concise, and easy for the reader to understand. Avoid unnecessary jargon or technical terms, and write in a direct and straightforward style.
Abbreviations and acronyms
An abbreviation is any shortened version of a longer word, while an acronym is an abbreviation (the first letter of each word).
Abbreviations and acronyms are specific to both the company and industry, so they are customized and constantly updated. Still, use them only when necessary. Define them on first use in the document, followed by the abbreviation or acronym in parenthesis. (e.g., “Virtual Private Network (VPN)”)
Use abbreviations and acronyms consistently throughout all documentation.
[The table below is for illustrative purposes. Replace the acronyms and abbreviations with industry- and company-specific examples.]
| Acronym | What it stands for |
|---|---|
| API | Application Programming Interface |
| GUI | Graphical User Interface |
| LAN | Local Area Network |
| RAM | Random Access Memory |
| SSL | Secure Sockets Layer |
| URL | Uniform Resource Locator |
| VPN | Virtual Private Network |
| WAN | Wide Area Network |
| UI | User Interface |
| IDE | Integrated Development Environment |
| SQL | Structured Query Language |
Punctuation
Punctuation isn’t noticeable when it’s done right. But when it’s done incorrectly, it can change the meaning of the text.
Let’s eat, Grandma.
this is a classic example of a comma placement to die for.
Let’s eat Grandma.
Knowing all the rules all the time requires a book alone (try the Chicago Manual of Style, listed below), but this list is a good start.
- Use periods to abbreviate units of measurement.
Example: “6 ft.” for “6 feet” - Use hyphens to join compound adjectives.
Example: “high-quality” and “user-friendly.” - Use hyphens to indicate ranges.
Example: “pages 25-30” - Use quotation marks to enclose direct quotations.
- Use parentheses to set off supplementary information.
- Use commas to separate items in a list unless the list contains only two items (use “and” instead).
- Use a semicolon to separate independent clauses. (Reminder: An independent clause is a group of words that can stand alone as a complete sentence.)
Example: The team worked on the project for months; it’s finally ready to present to the client.
Numbers and Units
- Spell the number at the beginning of a sentence, otherwise, use the numeral (unless the words create a more common phrase).
- Use an en dash (–) for a range of numbers (e.g., “5–10” instead of “5 to 10”).
- [Numbers and units are essential to get right for some internal docs, so it might be worth linking to a guide or resource like the ones linked below if the company needs more detailed options.]
Proofreading
We all make mistakes. That’s why it’s so important to edit your work.
The quick checks below will help, but it’s also a good idea to keep track of mistakes you make regularly. Check out the [sample checklist] for a more complete list of things to check.
- Spelling.
- Punctuation.
- Do your verb tenses match throughout? And the subject-verb tense match, too?
- Clear and concise – have you cut out everything that can be cut?
- Check that your tone and voice match throughout the piece.
[Does the company recommend Grammarly or ProWriting Aid or some other tool? If so, link to it here. If not, consider adding a section linking to a few options here.]
Citations and References
Refer to other resources in your writing, and even embed a quote or code snippet, as long as you give credit.
- Link to the cited source inline, in parenthesis next to the reference, or underneath a cited quote or code snippet.
[Some companies prefer not to link to outside sources unless they are approved sources. This is something to clarify before finalizing the style guide.]
Links to Additional Resources
This style guide includes a small selection of language items, but you can also reference additional sources to see how to cite or include something in your writing. Refer to the linked [Internal Teams Style Guide Questionnaire] to help decide what resources to link here. Typically they’d include a specific professional style guide and potentially a link to other specific grammar-related references.