Answer a short questionnaire and leave with a working style guide your team can adopt today. About an hour, start to finish.
Start from a preset
Questionnaire
About this template
00 - How to use this template
Internal Documentation Style Guide Template, created by Katrina Moody. Licensed CC BY-SA 4.0.
This page is for whoever sets up your team's guide. Read it, use it, then delete it. It doesn't belong in your published guide.
Why a template for internal docs?
Most style guide examples are written for public content: marketing sites, brand voice, product UI. Internal docs have different problems. They're written by people whose main job isn't writing, they live in several tools at once, and they go stale fast.
A copy-and-paste style guide won't fix that. For internal docs, you also have to consider your team's culture and how your team actually works. This template gives you a solid starting point, and the questionnaire helps you make it yours.
How to build your guide
Fill out the questionnaire (the Style Guide Questionnaire for Internal Teams, included with this template) with the people who write your docs. Plan about an hour.
Pick your sections. In questionnaire question A8, mark each section Now, Later, or Skip. Start with the Now sections. A good first version beats a perfect one that never ships.
Customize each section using your answers (see below).
Delete every template note, including this page.
Run the checklist in §02 one last time, then share your guide (see questionnaire question E6).
How to customize
The template uses three kinds of markers:
[Text in brackets] is a placeholder. Replace it with your team's information: "[Company]" becomes your company name.
Customize notes look like this:
Customize (B5): If you chose third person, flip these examples.
The code in parentheses is the questionnaire question that decides that rule. Make the change, then delete the note.
Template notes appear at the top of each section:
Template note: Notes like this are instructions for whoever sets up the guide. Delete them before you publish.
Before you publish, search the whole guide for "Customize" and "Template note," and scan for any [bracketed placeholders]. If you find any, the guide isn't finished yet.
A few tips
Every team is different. What works for one may not work for another. Change anything that doesn't fit, and cut anything you don't need.
Name an owner (questionnaire question A2). A guide nobody owns is one that goes stale.
Share it widely. Link it from your doc templates, onboarding, and team channels so people actually find it.
About 10 minutes. The basics: who you are, where your docs live, and what this guide needs to fix.
A1Your team or company name
Why it matters: Your own name is the word your docs use most. If it's written three different ways, readers notice. In internal docs, those readers are also writers. They'll copy the mistake into everything they write, inside and outside the company.
Feeds §03Feeds §06
A2Style guide owner
Why it matters: A guide with no owner goes stale. A name (or a role, if people change) gives questions somewhere to go.
Feeds §03Feeds §12
A3Who decides, and by when
Why it matters: Style guides stall when everyone has an opinion and no one has the final word. Set a date for a "good enough" first version. You'll improve it later.
The target date is for your planning. It won't appear in the guide.
Feeds §12
A4Where your docs live
Why it matters: Your tools change the rules. For example, Confluence can show an inline link with the page's icon and title, and some teams prefer that format for every link. If your docs live in several places, the template's Documentation Map (§05) helps everyone find the right one.
Feeds §04Feeds §05
A5What this guide will cover
Why it matters: Scope keeps the guide focused. Anything not on this list doesn't have to follow the guide, which saves arguments later.
Feeds §03Feeds §05
A6Doc types you write most
Why it matters: The template includes a starter skeleton for each doc type. Your top three get the most attention.
Feeds §05
A7Your top 3 doc pain points
Why it matters: These answers decide what goes on your Quick Rules card (§01), the one page most people will actually read. Fix the pain points first.
Name — Not decided yet; Common mistakes to avoid (for example, "Acme inc," "ACME," or "AcmeCo") — Not decided yet
Style guide owner
Name / role — Not decided yet; Best way to reach them (for example, email or a Slack channel) — Not decided yet
Who decides, and by when
People helping make decisions — Not decided yet; Final sign-off — Not decided yet; Target date for the first version — Not decided yet
Where your docs live
Check all that apply: — Not decided yet; Which one is the source of truth when docs disagree? — Not decided yet
What this guide will cover
Not decided yet
Doc types you write most
Not decided yet
Your top 3 doc pain points
Not decided yet
Audience & voice
Question
Our answer
Who reads your docs
Check all that apply: — Not decided yet; Do different readers use different parts of the docs? — Not decided yet; If yes, which readers use which docs? (For example, "Support uses the troubleshooting articles; new hires use onboarding.") — Not decided yet; How technical are most readers? — Not decided yet
Readers who speak English as a second language
Readers who speak English as a second language — Not decided yet; Do people use translation tools to read your docs? — Not decided yet
US or UK English
Not decided yet
Overall tone
Not decided yet
How you talk to the reader
Address the reader as: — Not decided yet; Use "we" for your team or company? — Not decided yet
Contractions
Not decided yet
Emoji, GIFs, and humor
Not decided yet
Your reference style guide
Main reference: — Not decided yet; For grammar and punctuation questions the main reference doesn't answer: — Not decided yet
Existing brand or voice guidelines
Not decided yet
Formatting
Question
Our answer
Capitalization for titles and headings
Page titles: — Not decided yet; Headings inside a page: — Not decided yet
Lists
End punctuation in list items: — Not decided yet; Start each item with a capital letter? — Not decided yet
The serial comma
Not decided yet
Bold and italics
Not decided yet
Numbers
Numbers — Not decided yet; Ranges: — Not decided yet; Units of measure your docs use often (for example, GB, MB, px, ft, kg): — Not decided yet
Dates, times, and time zones
Dates: — Not decided yet; Times: — Not decided yet; Time zones: — Not decided yet
UI elements, code, and keyboard keys
Button names, menu items, and other on-screen labels: — Not decided yet; Keyboard shortcuts: — Not decided yet
Callouts: notes, tips, and warnings
Which callout labels will you use? Check all that apply: — Not decided yet; Does your tool have built-in callout boxes (like Confluence panels or Notion callouts)? — Not decided yet
Links
Linking to outside websites: — Not decided yet; Does your tool have a special link style (like Confluence smart links with the page icon and title)? — Not decided yet
Images, screenshots, and video
Screenshots: — Not decided yet; Preferred file formats (for example, PNG for screenshots, GIF or MP4 for short demos): — Not decided yet
Color
Not decided yet
Citations and sources
Not decided yet
Content policies
Question
Our answer
Accessibility
Accessibility target: — Not decided yet; Do any of your readers use assistive technology (screen readers, screen magnifiers, voice control)? — Not decided yet; How will you check docs for accessibility? Check all that apply: — Not decided yet
Inclusive language
Do you already have inclusive language guidelines? — Not decided yet; Terms your team has retired, and what to use instead (for example, whitelist → allowlist; master/slave → primary/replica): — Not decided yet
Sensitive information
What counts as sensitive information for your team? Check all that apply: — Not decided yet; Where do secrets live instead (for example, your password manager)? — Not decided yet; Who answers questions about where sensitive information should live (for example, customer addresses or phone numbers)? — Not decided yet; Who should people contact if something sensitive gets posted by mistake? — Not decided yet
Legal and regulatory requirements
Do any of these apply to your docs? Check all that apply: — Not decided yet; Required labels or notices (for example, "Confidential: Internal use only"): — Not decided yet
AI writing tools
Does your company have a policy on AI use for internal purposes already? — Not decided yet; Can writers use AI tools for docs? — Not decided yet; What can AI help with? Check all that apply: — Not decided yet; Should docs say when AI helped write them? — Not decided yet
Maintenance
Question
Our answer
Who contributes to docs
Not decided yet
How changes get approved
Small fixes (typos, broken links): — Not decided yet; Bigger changes (new docs, rewrites, new rules for this guide): — Not decided yet; What counts as a bigger change? (For example, anything that changes steps, a policy, or a rule in this guide.) — Not decided yet
How people suggest changes to this guide
Not decided yet
Review schedule
How often will someone review this guide? — Not decided yet; Show a "Last reviewed" date on docs? — Not decided yet
Retiring old docs
When a doc is out of date and nobody will update it: — Not decided yet; Who decides? — Not decided yet
Sharing the guide
Where will the finished guide live? — Not decided yet; How will people find out about it? Check all that apply: — Not decided yet
01 - Quick rules
The rules that come up most, on one page. When you have a question this page doesn't answer, follow the section link.
Voice
Talk to the reader as "you" (§06).
Use active voice and present tense: "The finance team approves requests" (§06).
Keep it simple. Short sentences, common words, no idioms (§06, §09).
Structure
Use sentence case for page titles, and make titles specific: "Request time off" (§04).
Put headings in order. Don't skip levels (§04).
Use numbered lists for steps and bullets for everything else (§04).
Start each step with the action: "Select Save" (§04).
Bold buttons and menu names. Use code formatting for commands and file names (§04).
Words and numbers
Spell out acronyms on first use, unless everyone knows them, like PDF (§06).
Use the serial comma: "docs, slides, and spreadsheets" (§06).
Use numerals for technical values: "5 GB," "version 2." Spell out zero through nine for everyday counts: "three steps" (§06).
Write dates like this: November 13, 2026. Add a time zone for meetings and deadlines (§06).
Links, images, and safety
Use descriptive link text: "See the expense policy," not "click here" (§04).
Add alt text to images, and never use color as the only way to show meaning (§07).
Never put passwords or customer data in docs. Say where to find them instead (§10).
Before you publish, run the checklist in §02.
02 - Before you publish: editing checklist
Run through this list before you publish or update any doc. It takes a few minutes, and it catches most of what readers would trip over.
Content
☐ The title says what the doc helps you do (§04).
☐ The most important information comes first.
☐ You followed the steps yourself, and they work (§04).
☐ Facts, names, and numbers are correct, especially anything drafted with AI (§11).
Language
☐ Spelling and grammar are checked. Run your tool's spell-check.
☐ Wordy and awkward phrasing is cut (§06).
☐ The doc talks to the reader as "you," in active voice and present tense (§06).
☐ Acronyms are spelled out on first use, and terms match the word list (§06).
Structure and formatting
☐ Headings are in order, with no extra formatting inside them (§04).
☐ The doc isn't mostly lists. If a section needs explaining, it's a paragraph (§04).
☐ Buttons and menu names are bold. Code, file names, and variables use code formatting (§04).
☐ No more than one callout per section (§04).
Links
☐ Every link works. Check links to shared files (like Google Drive) closely, since those get moved and deleted often.
☐ Every Slack channel, team, or tool named in the doc still exists and hasn't been renamed.
☐ Link text describes where it goes, and links point to the source of truth (§04).
☐ [Your tool's link style, for example: internal links use Confluence smart links.]
Accessibility and safety
☐ Every meaningful image has alt text, and no important text appears only in an image (§07).
☐ Color isn't the only way to show meaning (§07).
☐ No passwords, customer data, or other sensitive information, including in screenshots (§10).
Last step
☐ The doc lists an owner and a "Last reviewed" date (§12).
☐ If this is a new kind of doc or a new location, the Documentation Map is updated (§05).
Make it yours: Keep track of the mistakes you make most often, and add them to your own copy of this list. That's how this checklist started: as one editor's mental checklist that kept growing.
03 - Introduction
Welcome to the [Company] internal style guide!
This guide helps everyone on the team write docs that are clear, consistent, and easy to find. You don't need to be a professional writer to use it. Most of the time, you only need the first two sections.
How to use this guide
Start with §01 Quick Rules. It covers the rules that come up most, on one page.
Before you publish anything, run through §02, the editing checklist.
Look up everything else when a question comes up. You don't need to memorize it.
Who this guide is for
Anyone who writes or updates [Company] internal docs, including [knowledge base articles, processes, onboarding docs, and team updates].
What's in this guide
Section
What it covers
§01 Quick Rules
The most important rules, on one page
§02 Before You Publish
An editing checklist to use every time
§04 Structure & Formatting
Headings, lists, steps, links, images, and more
§05 Document Types & Templates
Starter templates and where our docs live
§06 Language & Grammar
Voice, tone, word choice, punctuation, and numbers
§07 Accessibility
Making docs work for everyone
§08 Inclusive Language
Writing that welcomes every reader
§09 Writing for Non-Native English Readers
Clear writing that translates well
§10 Sensitive Information
What never goes in docs
§11 Using AI Writing Tools
When and how to use AI for docs
§12 Contributing, Review & Maintenance
How docs (and this guide) stay up to date
§13 Resources
References, tools, and further reading
Questions or suggestions?
This guide is a living document. If something's unclear, missing, or just not working, contact [guide owner and the best way to reach them, from A2]. To suggest a change, see §12.
Last reviewed: [date]
04 - Structure & formatting
How you structure and format a doc decides whether people can find what they need. Good formatting makes docs easier to scan, follow, and update.
Titles and headings
Use sentence case for page titles: "How to reset your password." Capitalize only the first word and proper nouns.
Use sentence case for headings inside a page.
Make titles specific. Readers should know what they'll get before they click: "Request time off," not "PTO stuff."
Use one H1 (the page title), then headings in order. Don't skip levels (H2 to H4). Readers and screen readers use headings to navigate (see §07).
Put the most important words first in a heading, so it's easy to scan.
Lists
Lists break content into pieces that are easy to scan. But if everything on a page is a list, nothing is. Use paragraphs when ideas need explaining.
Use numbered lists for steps in order. Use bullets for everything else.
Make items parallel. If one item starts with a verb, they all should.
Start each item with a capital letter.
End items with periods only when they're complete sentences.
Keep nesting to two levels. If you need more, the content probably needs headings instead.
Steps
One action per step.
Start each step with the action: "Select Save."
Say where before what: "In Settings, select Notifications."
Put conditions first: "If you don't see the menu, refresh the page."
Tell readers what happens when it isn't obvious: "A confirmation message appears."
For full step-by-step templates, see §05.
Bold, italics, and emphasis
Use bold for UI labels and for warnings readers must not miss.
Use italics for the titles of books, reports, and other works.
Don't underline text that isn't a link. Readers will try to click it.
Don't use ALL CAPS for emphasis. It reads like shouting and is harder to read.
Use emoji sparingly: at most one per heading or message, and never in place of words (see §07).
If everything is bold, nothing is. Save emphasis for what matters most.
UI elements, code, and keyboard keys
Bold the names of buttons, menus, and other on-screen labels, and match the screen exactly: "Select Save changes."
Use "select" for buttons and menu items. It works whether someone uses a mouse, touchscreen, or keyboard.
Use code formatting for commands, file names, file paths, and variables: config.yml, npm install.
Write keyboard shortcuts like this: Ctrl+C (Windows), Command+C (Mac).
Callouts: notes, tips, and warnings
Use callouts to set apart information that doesn't fit in the main text. As a rule of thumb, use no more than one per section. When every other paragraph is a note, readers stop reading them.
Label
Use it for
Note
Helpful extra information
Tip
A shortcut or easier way to do something
Important
Something readers need to know to succeed
Warning
Anything that could lose data, break something, or create a security risk
[Use your tool's built-in callout boxes, like Confluence panels or Notion callouts.]
Links
Write descriptive link text: "See the onboarding checklist," not "click here."
Link to the source of truth, not a copy of it.
Don't overdo it. Too many links make a page hard to read. Link the first mention, not every mention.
Linking outside the company: link only to reputable sources: official vendor docs, standards bodies, and the sources in §13.
[If your tool has a special link style, like Confluence smart links with the page icon and title, say when to use it.]
Images, screenshots, and video
Use images and video to show what words can't, like where a button is or how a process flows. They should support the text, not replace it.
Add alt text to every meaningful image (see §07).
Crop screenshots to the part that matters.
Blur or crop anything sensitive, like customer names, emails, or passwords (see §10).
Choose the right format: a short GIF or video to show an action, a screenshot to show where something is.
Get permission to use images or media from outside sources. Yes, even internally.
Update screenshots when the screen changes. An outdated screenshot causes more confusion than none at all.
Our image settings: [maximum width, file formats, and highlight or arrow style, from C10.]
Tables
Use tables for data you want to compare, not for page layout.
Always include a header row.
Keep them simple. If a table needs scrolling in every direction, split it up or use a list.
Color
Never use color as the only way to show meaning (see §07).
[Brand colors for highlights, tables, or diagrams, if you use them, from C11.]
06 - Language & grammar
Clear, concise, and easy for anyone on the team to read.
Our references
This guide covers the rules our team uses most. For anything it doesn't cover:
Grammar and punctuation:The Chicago Manual of Style, 18th edition. Chicago's Q&A pages are free to read.
Spelling:Merriam-Webster. When it lists more than one spelling, use the first one.
If this guide and one of our references disagree on a language or grammar question, follow this guide.
Tone
Tone is the mood of your writing. Ours is professional but friendly: easy to read, still trustworthy. Write the way you'd explain something to one of your coworkers.
Instead of this
Write this
Utilize the dashboard functionality to facilitate report generation.
Use the dashboard to create reports.
It should be noted that access requests may take some time.
Access requests can take up to two days.
This is super easy, just hit the button lol
Select Submit.
Be concise. Cut words that don't add meaning.
Be specific. "Up to two days" beats "some time."
Skip idioms and slang. They confuse readers who speak English as a second language and trip up translation tools (see §09).
Voice
Voice is how your docs sound to the reader. Keep it consistent across every doc, no matter who writes it.
Talk to the reader as "you"
Write as though you're talking to the person reading. For steps, start with the action (this is called the imperative): "Select Export." The "you" is implied.
Yes: You can export reports as PDFs. To export one, select Export.
No: The user can export reports as PDFs. Users should select Export.
Use the third person for what software or other people do: "The system sends a confirmation email."
Use "we" for the team
In internal docs, the reader is part of the team, so "we" includes them: "We ship updates on Fridays." It makes docs feel personal and helps new teammates feel like they belong.
Make it clear which "we." If it could mean the company, your team, or the docs team, name the team: "The support team reviews tickets daily."
Use "you" for steps, not "we." Write "Select Save," not "Now we select Save."
Don't let "we" hide an owner. "We should update this page" leaves it to no one. Name who: "[Team or person] updates this page each quarter."
Why this differs from some style guides: Customer-facing guides, like Microsoft's, often avoid "we" because there it means the company talking at a customer. In internal docs, "we" includes the reader.
Use active voice
The subject does the action in active voice. It's shorter and makes clear who does what.
Yes: The finance team approves all purchase requests.
No: All purchase requests are approved by the finance team.
Not sure which one you wrote? Try the zombie test. Add "by zombies" after the verb. If the sentence still makes sense, it's passive.
"All purchase requests are approved by zombies." Makes sense, so it's passive.
"The finance team approves by zombies all purchase requests." Nonsense, so it's active.
Passive voice is fine when the actor doesn't matter or is unknown: "The file was deleted."
Use present tense
Docs describe how things work now. Future tense makes readers wonder when it'll be true.
Yes: The report shows last month's totals.
No: The report will show last month's totals.
Use contractions
Common contractions (it's, you're, don't) sound friendly and natural. Avoid awkward ones like there'd, it'll, and they'd.
For warnings where a missed word could cause harm, spell it out: "Do not delete this folder."
Use gender-neutral language
When you don't know someone's gender, use "they," or rewrite with "you" or a role ("the requester"). See §08 for more.
Spelling and word choice
[Company] is always written exactly this way. Not: [common mistakes from A1].
Use US English spelling. Check Merriam-Webster, and use the first spelling it lists.
No fuzzy standards. If a rule says "reputable," "appropriate," "sparingly," or "when needed," say who decides or how to tell. "Use callouts sparingly" leaves everyone guessing; "No more than one callout per section" doesn't.
Word list
Use the same word for the same thing, every time. When a new term comes up, suggest it to [guide owner, from A2], who adds it here (see §12).
Use
Not
Notes
email
e-mail
log in (verb), login (noun)
log-in
"Log in to the portal." "Your login expired."
set up (verb), setup (noun)
set-up
"Set up your account." "Finish the setup."
back up (verb), backup (noun)
back-up
"Back up your files." "Restore from the backup."
check out (verb), checkout (noun)
check-out
"Check out the new dashboard." "Go to checkout."
allowlist, blocklist
whitelist, blacklist
See §08
[Your product or tool name]
[Common misspelling]
Abbreviations and acronyms
Spell it out first. On first use, write the full term followed by the acronym in parentheses: "single sign-on (SSO)." After that, use the acronym.
Skip the spell-out for acronyms everyone knows better than the full term, like PDF, URL, and USB. If spelling it out would make readers stop and think ("universal serial bus?"), don't. A good sign: the acronym is in the dictionary.
Use only acronyms your readers know. If most readers would have to stop and think, spell it out.
Don't introduce an acronym you only use once.
Skip the possessive. Write "the API settings," not "the API's settings."
Don't start a heading with a new acronym. Define it in the text first.
Write out common Latin abbreviations. Use "for example" instead of e.g., "that is" instead of i.e., and "and so on" (or a complete list) instead of etc. They're easy to mix up and hard for readers who speak English as a second language.
Acronym
Meaning
Spell out on first use?
API
application programming interface
Yes
FAQ
frequently asked questions
No
PDF
Portable Document Format
No
SSO
single sign-on
Yes
TLS
Transport Layer Security
Yes
UI
user interface
Yes
URL
uniform resource locator
No
VPN
virtual private network
Yes
[Your acronym]
[What it means]
[Yes or no]
Punctuation
Punctuation isn't noticeable when it's done right. But when it's done wrong, it can change the meaning.
Let's eat, Grandma.
Let's eat Grandma.
This is a classic example of a comma placement to die for.
In a list of three or more, put a comma before the last item (the serial comma, also called the Oxford comma): "docs, slides, and spreadsheets."
When two words work together to describe a noun, hyphenate them (a compound modifier): "a high-quality image." No hyphen when they come after the noun: "the image is high quality."
Use an en dash (–) for ranges: "pages 5–10," "9:00 AM–5:00 PM." It's a little longer than a hyphen.
Mac: Option + hyphen
Windows: Alt + 0150 (on the number pad)
HTML or Markdown:–
Use em dashes (—) with no spaces, and no more than one per paragraph. A comma, colon, or parentheses usually work better.
Mac: Option + Shift + hyphen
Windows: Alt + 0151 (on the number pad)
HTML or Markdown:—
Put periods and commas inside quotation marks.
Yes: Call it "the dashboard."
No: Call it "the dashboard".
Use semicolons rarely. If a period works, use a period. Two short sentences are usually clearer than one long one.
Instead of: The team worked on the project for months; it's finally ready to present.
Try: The team worked on the project for months. It's finally ready to present.
Skip exclamation points in most docs. Save them for real excitement, like a launch announcement.
Numbers and units
Technical values are always numerals: version numbers, measurements, pixels, ports, error codes, numbers in the UI, and anything the reader types. Put a space before a unit: "5 GB," "3 inches," "16 px."
For everyday counts in sentences, spell out zero through nine and use numerals for 10 and up: "five steps," "15 users."
Spell out a number that starts a sentence, or rewrite the sentence so it doesn't start with one.
Use commas in numbers with four or more digits: "1,000," "25,000." Except years, ports, version numbers, and codes: "2026," "port 8080."
Units we use often: [list from C5, for example GB, MB, px].
Dates and times
Write dates as month, day, year, with the month spelled out: November 13, 2026. Don't use ordinals like "November 13th."
Avoid all-number dates like 11/12/2026 in running text. Readers in different countries read them differently.
Times: 3:00 PM. Use "noon" and "midnight," not "12:00 noon."
Time zones: Always include one for meetings and deadlines: "3:00 PM ET." For global teams, use Coordinated Universal Time (UTC).
Citations and sources
When you borrow from another source, credit it. In most internal docs, a link is enough.
Internal docs feel private, so people paste things they shouldn't. But internal docs get shared, exported, screenshotted, and searched. Treat every doc like it could leave the building.
Never put these in docs
Passwords, API keys, tokens, and other credentials
[Customer names and data]
[Employee personal information, like personal email addresses, home addresses, and phone numbers]
[Financial account details]
[Health information]
[Security details, like server names, IP addresses, and internal URLs]
[Unreleased product or business plans]
Point to it instead
Tell readers where to find sensitive information without including it:
Yes: Get the admin password from the "Payroll admin" entry in [password manager].
No: The admin password is Summer2026!
Where it lives: [password manager or secure location, from D3]
Questions about where something should live? Ask [contact, from D3].
Use placeholders in examples
Credentials:YOUR_API_KEY, your-password-here
Websites and email: example.com, name@example.com (these domains are reserved for examples)
Phone numbers: 555-0100 through 555-0199 (reserved for fictional use in the US)
People: made-up names, never real customers or coworkers
Check screenshots before you share
Blur or crop names, email addresses, account numbers, and anything else on the list above. Also check the edges of the screen: browser tabs, bookmarks, and notifications can give away more than you think.
Labels and legal requirements
Label confidential docs: [required notice from D4, for example "Confidential: Internal use only"]
Our requirements: [privacy laws, regulations, or audits from D4]
Not sure? Ask [legal or compliance contact] before you publish.
If something sensitive gets posted
Tell [contact, from D3] right away.
Remove it, but don't assume that's enough. Page history, search indexes, and notifications can keep a copy.
If it was a password or key, change it. Once a secret has been posted, treat it as public.
Coming later
These sections are planned for a later version of this guide:
Document Types & Templates
Accessibility
Inclusive Language
Writing for Non-Native English Readers
Using AI Writing Tools
Contributing, Review & Maintenance
Resources
Generated with Style guide builder for internal documentation by Katrina Moody (katrinamoody.com). Template licensed CC BY-SA 4.0.
Internal style guide
Our decisions
Setup
Question
Our answer
Your team or company name
Name — Not decided yet; Common mistakes to avoid (for example, "Acme inc," "ACME," or "AcmeCo") — Not decided yet
Style guide owner
Name / role — Not decided yet; Best way to reach them (for example, email or a Slack channel) — Not decided yet
Who decides, and by when
People helping make decisions — Not decided yet; Final sign-off — Not decided yet; Target date for the first version — Not decided yet
Where your docs live
Check all that apply: — Not decided yet; Which one is the source of truth when docs disagree? — Not decided yet
What this guide will cover
Not decided yet
Doc types you write most
Not decided yet
Your top 3 doc pain points
Not decided yet
Audience & voice
Question
Our answer
Who reads your docs
Check all that apply: — Not decided yet; Do different readers use different parts of the docs? — Not decided yet; If yes, which readers use which docs? (For example, "Support uses the troubleshooting articles; new hires use onboarding.") — Not decided yet; How technical are most readers? — Not decided yet
Readers who speak English as a second language
Readers who speak English as a second language — Not decided yet; Do people use translation tools to read your docs? — Not decided yet
US or UK English
Not decided yet
Overall tone
Not decided yet
How you talk to the reader
Address the reader as: — Not decided yet; Use "we" for your team or company? — Not decided yet
Contractions
Not decided yet
Emoji, GIFs, and humor
Not decided yet
Your reference style guide
Main reference: — Not decided yet; For grammar and punctuation questions the main reference doesn't answer: — Not decided yet
Existing brand or voice guidelines
Not decided yet
Formatting
Question
Our answer
Capitalization for titles and headings
Page titles: — Not decided yet; Headings inside a page: — Not decided yet
Lists
End punctuation in list items: — Not decided yet; Start each item with a capital letter? — Not decided yet
The serial comma
Not decided yet
Bold and italics
Not decided yet
Numbers
Numbers — Not decided yet; Ranges: — Not decided yet; Units of measure your docs use often (for example, GB, MB, px, ft, kg): — Not decided yet
Dates, times, and time zones
Dates: — Not decided yet; Times: — Not decided yet; Time zones: — Not decided yet
UI elements, code, and keyboard keys
Button names, menu items, and other on-screen labels: — Not decided yet; Keyboard shortcuts: — Not decided yet
Callouts: notes, tips, and warnings
Which callout labels will you use? Check all that apply: — Not decided yet; Does your tool have built-in callout boxes (like Confluence panels or Notion callouts)? — Not decided yet
Links
Linking to outside websites: — Not decided yet; Does your tool have a special link style (like Confluence smart links with the page icon and title)? — Not decided yet
Images, screenshots, and video
Screenshots: — Not decided yet; Preferred file formats (for example, PNG for screenshots, GIF or MP4 for short demos): — Not decided yet
Color
Not decided yet
Citations and sources
Not decided yet
Content policies
Question
Our answer
Accessibility
Accessibility target: — Not decided yet; Do any of your readers use assistive technology (screen readers, screen magnifiers, voice control)? — Not decided yet; How will you check docs for accessibility? Check all that apply: — Not decided yet
Inclusive language
Do you already have inclusive language guidelines? — Not decided yet; Terms your team has retired, and what to use instead (for example, whitelist → allowlist; master/slave → primary/replica): — Not decided yet
Sensitive information
What counts as sensitive information for your team? Check all that apply: — Not decided yet; Where do secrets live instead (for example, your password manager)? — Not decided yet; Who answers questions about where sensitive information should live (for example, customer addresses or phone numbers)? — Not decided yet; Who should people contact if something sensitive gets posted by mistake? — Not decided yet
Legal and regulatory requirements
Do any of these apply to your docs? Check all that apply: — Not decided yet; Required labels or notices (for example, "Confidential: Internal use only"): — Not decided yet
AI writing tools
Does your company have a policy on AI use for internal purposes already? — Not decided yet; Can writers use AI tools for docs? — Not decided yet; What can AI help with? Check all that apply: — Not decided yet; Should docs say when AI helped write them? — Not decided yet
Maintenance
Question
Our answer
Who contributes to docs
Not decided yet
How changes get approved
Small fixes (typos, broken links): — Not decided yet; Bigger changes (new docs, rewrites, new rules for this guide): — Not decided yet; What counts as a bigger change? (For example, anything that changes steps, a policy, or a rule in this guide.) — Not decided yet
How people suggest changes to this guide
Not decided yet
Review schedule
How often will someone review this guide? — Not decided yet; Show a "Last reviewed" date on docs? — Not decided yet
Retiring old docs
When a doc is out of date and nobody will update it: — Not decided yet; Who decides? — Not decided yet
Sharing the guide
Where will the finished guide live? — Not decided yet; How will people find out about it? Check all that apply: — Not decided yet
01 - Quick rules
The rules that come up most, on one page. When you have a question this page doesn't answer, follow the section link.
Customize (A7): Put the rules that fix your team's top pain points first. Keep this page to one screen.
Your answer: A7: not answered
Voice
Talk to the reader as "you" (§06).
Use active voice and present tense: "The finance team approves requests" (§06).
Keep it simple. Short sentences, common words, no idioms (§06, §09).
Structure
Use sentence case for page titles, and make titles specific: "Request time off" (§04).
Put headings in order. Don't skip levels (§04).
Use numbered lists for steps and bullets for everything else (§04).
Start each step with the action: "Select Save" (§04).
Bold buttons and menu names. Use code formatting for commands and file names (§04).
Words and numbers
Spell out acronyms on first use, unless everyone knows them, like PDF (§06).
Use the serial comma: "docs, slides, and spreadsheets" (§06).
Use numerals for technical values: "5 GB," "version 2." Spell out zero through nine for everyday counts: "three steps" (§06).
Write dates like this: November 13, 2026. Add a time zone for meetings and deadlines (§06).
Links, images, and safety
Use descriptive link text: "See the expense policy," not "click here" (§04).
Add alt text to images, and never use color as the only way to show meaning (§07).
Never put passwords or customer data in docs. Say where to find them instead (§10).
Before you publish, run the checklist in §02.
02 - Before you publish: editing checklist
Run through this list before you publish or update any doc. It takes a few minutes, and it catches most of what readers would trip over.
Customize (A7): Move the checks that match your team's top pain points to the top of the list.
Your answer: A7: not answered
Content
☐ The title says what the doc helps you do (§04).
☐ The most important information comes first.
☐ You followed the steps yourself, and they work (§04).
☐ Facts, names, and numbers are correct, especially anything drafted with AI (§11).
Language
☐ Spelling and grammar are checked. Run your tool's spell-check.
☐ Wordy and awkward phrasing is cut (§06).
☐ The doc talks to the reader as "you," in active voice and present tense (§06).
☐ Acronyms are spelled out on first use, and terms match the word list (§06).
Structure and formatting
☐ Headings are in order, with no extra formatting inside them (§04).
☐ The doc isn't mostly lists. If a section needs explaining, it's a paragraph (§04).
☐ Buttons and menu names are bold. Code, file names, and variables use code formatting (§04).
☐ No more than one callout per section (§04).
Links
☐ Every link works. Check links to shared files (like Google Drive) closely, since those get moved and deleted often.
☐ Every Slack channel, team, or tool named in the doc still exists and hasn't been renamed.
☐ Link text describes where it goes, and links point to the source of truth (§04).
☐ [Your tool's link style, for example: internal links use Confluence smart links.]
Accessibility and safety
☐ Every meaningful image has alt text, and no important text appears only in an image (§07).
☐ Color isn't the only way to show meaning (§07).
☐ No passwords, customer data, or other sensitive information, including in screenshots (§10).
Last step
☐ The doc lists an owner and a "Last reviewed" date (§12).
☐ If this is a new kind of doc or a new location, the Documentation Map is updated (§05).
Make it yours: Keep track of the mistakes you make most often, and add them to your own copy of this list. That's how this checklist started: as one editor's mental checklist that kept growing.
03 - Introduction
Welcome to the [Company] internal style guide!
This guide helps everyone on the team write docs that are clear, consistent, and easy to find. You don't need to be a professional writer to use it. Most of the time, you only need the first two sections.
How to use this guide
Start with §01 Quick Rules. It covers the rules that come up most, on one page.
Before you publish anything, run through §02, the editing checklist.
Look up everything else when a question comes up. You don't need to memorize it.
Who this guide is for
Anyone who writes or updates [Company] internal docs, including [knowledge base articles, processes, onboarding docs, and team updates].
Customize (A5, B1): List what this guide covers and who writes those docs.
Your answer: A5: not answered; B1: not answered; B1b: not answered; B1c: not answered; B1d: not answered
What's in this guide
Section
What it covers
§01 Quick Rules
The most important rules, on one page
§02 Before You Publish
An editing checklist to use every time
§04 Structure & Formatting
Headings, lists, steps, links, images, and more
§05 Document Types & Templates
Starter templates and where our docs live
§06 Language & Grammar
Voice, tone, word choice, punctuation, and numbers
§07 Accessibility
Making docs work for everyone
§08 Inclusive Language
Writing that welcomes every reader
§09 Writing for Non-Native English Readers
Clear writing that translates well
§10 Sensitive Information
What never goes in docs
§11 Using AI Writing Tools
When and how to use AI for docs
§12 Contributing, Review & Maintenance
How docs (and this guide) stay up to date
§13 Resources
References, tools, and further reading
Customize (A8): Remove rows for sections you skipped.
Your answer: A8: Quick Rules: now; Before You Publish: Editing Checklist: now; Introduction: now; Structure & Formatting: now; Document Types & Templates: later; Language & Grammar: now; Accessibility: later; Inclusive Language: later; Writing for Non-Native English Readers: later; Sensitive Information: now; Using AI Writing Tools: later; Contributing, Review & Maintenance: later; Resources: later
Questions or suggestions?
This guide is a living document. If something's unclear, missing, or just not working, contact [guide owner and the best way to reach them, from A2]. To suggest a change, see §12.
Last reviewed: [date]
04 - Structure & formatting
How you structure and format a doc decides whether people can find what they need. Good formatting makes docs easier to scan, follow, and update.
Titles and headings
Use sentence case for page titles: "How to reset your password." Capitalize only the first word and proper nouns.
Use sentence case for headings inside a page.
Make titles specific. Readers should know what they'll get before they click: "Request time off," not "PTO stuff."
Use one H1 (the page title), then headings in order. Don't skip levels (H2 to H4). Readers and screen readers use headings to navigate (see §07).
Put the most important words first in a heading, so it's easy to scan.
Customize (C1): If you chose Title Case, update the first rule and example.
Your answer: C1: not answered; C1b: not answered; C10: not answered; C10b: not answered; C11: not answered; C12: not answered
Lists
Lists break content into pieces that are easy to scan. But if everything on a page is a list, nothing is. Use paragraphs when ideas need explaining.
Use numbered lists for steps in order. Use bullets for everything else.
Make items parallel. If one item starts with a verb, they all should.
Start each item with a capital letter.
End items with periods only when they're complete sentences.
Keep nesting to two levels. If you need more, the content probably needs headings instead.
Customize (C2): Update the punctuation and capitalization rules to match your answers.
Your answer: C2: not answered; C2b: not answered
Steps
One action per step.
Start each step with the action: "Select Save."
Say where before what: "In Settings, select Notifications."
Put conditions first: "If you don't see the menu, refresh the page."
Tell readers what happens when it isn't obvious: "A confirmation message appears."
For full step-by-step templates, see §05.
Bold, italics, and emphasis
Use bold for UI labels and for warnings readers must not miss.
Use italics for the titles of books, reports, and other works.
Don't underline text that isn't a link. Readers will try to click it.
Don't use ALL CAPS for emphasis. It reads like shouting and is harder to read.
Use emoji sparingly: at most one per heading or message, and never in place of words (see §07).
If everything is bold, nothing is. Save emphasis for what matters most.
Customize (C4, B7): Update these rules if you chose your own bold and italics rule, or a different emoji policy.
Your answer: B7: not answered; C4: not answered
UI elements, code, and keyboard keys
Bold the names of buttons, menus, and other on-screen labels, and match the screen exactly: "Select Save changes."
Use "select" for buttons and menu items. It works whether someone uses a mouse, touchscreen, or keyboard.
Use code formatting for commands, file names, file paths, and variables: config.yml, npm install.
Write keyboard shortcuts like this: Ctrl+C (Windows), Command+C (Mac).
Customize (C7): Update these rules if you chose quotation marks for UI labels or a different shortcut style.
Your answer: C7: not answered; C7b: not answered
Callouts: notes, tips, and warnings
Use callouts to set apart information that doesn't fit in the main text. As a rule of thumb, use no more than one per section. When every other paragraph is a note, readers stop reading them.
Label
Use it for
Note
Helpful extra information
Tip
A shortcut or easier way to do something
Important
Something readers need to know to succeed
Warning
Anything that could lose data, break something, or create a security risk
[Use your tool's built-in callout boxes, like Confluence panels or Notion callouts.]
Customize (C8): Keep only the labels you chose, and name your tool's callout feature.
Your answer: C8: not answered; C8b: not answered
Links
Write descriptive link text: "See the onboarding checklist," not "click here."
Link to the source of truth, not a copy of it.
Don't overdo it. Too many links make a page hard to read. Link the first mention, not every mention.
Linking outside the company: link only to reputable sources: official vendor docs, standards bodies, and the sources in §13.
[If your tool has a special link style, like Confluence smart links with the page icon and title, say when to use it.]
Customize (C9b): Add your tool's link style, if it has one.
Your answer: C9b: not answered
Images, screenshots, and video
Use images and video to show what words can't, like where a button is or how a process flows. They should support the text, not replace it.
Add alt text to every meaningful image (see §07).
Crop screenshots to the part that matters.
Blur or crop anything sensitive, like customer names, emails, or passwords (see §10).
Choose the right format: a short GIF or video to show an action, a screenshot to show where something is.
Get permission to use images or media from outside sources. Yes, even internally.
Update screenshots when the screen changes. An outdated screenshot causes more confusion than none at all.
Our image settings: [maximum width, file formats, and highlight or arrow style, from C10.]
Customize (C10): Add your image sizes, formats, and annotation style.
Your answer: C10: not answered; C10b: not answered
Tables
Use tables for data you want to compare, not for page layout.
Always include a header row.
Keep them simple. If a table needs scrolling in every direction, split it up or use a list.
Color
Never use color as the only way to show meaning (see §07).
[Brand colors for highlights, tables, or diagrams, if you use them, from C11.]
Customize (C11): Add brand colors if you chose to use them. Otherwise, delete that line.
Your answer: C11: not answered
06 - Language & grammar
Clear, concise, and easy for anyone on the team to read.
Our references
This guide covers the rules our team uses most. For anything it doesn't cover:
Grammar and punctuation:The Chicago Manual of Style, 18th edition. Chicago's Q&A pages are free to read.
Spelling:Merriam-Webster. When it lists more than one spelling, use the first one.
If this guide and one of our references disagree on a language or grammar question, follow this guide.
Customize (B3, B8): Swap in your main reference, grammar fallback, and dictionary. For UK English, use an Oxford dictionary instead of Merriam-Webster.
Your answer: B3: not answered; B8: not answered; B8b: not answered
Tone
Tone is the mood of your writing. Ours is professional but friendly: easy to read, still trustworthy. Write the way you'd explain something to one of your coworkers.
Instead of this
Write this
Utilize the dashboard functionality to facilitate report generation.
Use the dashboard to create reports.
It should be noted that access requests may take some time.
Access requests can take up to two days.
This is super easy, just hit the button lol
Select Submit.
Be concise. Cut words that don't add meaning.
Be specific. "Up to two days" beats "some time."
Skip idioms and slang. They confuse readers who speak English as a second language and trip up translation tools (see §09).
Customize (B4): If you chose formal or conversational, rewrite the first paragraph and the table to match.
Your answer: B4: not answered
Voice
Voice is how your docs sound to the reader. Keep it consistent across every doc, no matter who writes it.
Talk to the reader as "you"
Write as though you're talking to the person reading. For steps, start with the action (this is called the imperative): "Select Export." The "you" is implied.
Yes: You can export reports as PDFs. To export one, select Export.
No: The user can export reports as PDFs. Users should select Export.
Use the third person for what software or other people do: "The system sends a confirmation email."
Customize (B5): If you chose third person, flip these examples and explain why (for example, formal compliance docs).
Your answer: B5: not answered; B5b: not answered
Use "we" for the team
In internal docs, the reader is part of the team, so "we" includes them: "We ship updates on Fridays." It makes docs feel personal and helps new teammates feel like they belong.
Make it clear which "we." If it could mean the company, your team, or the docs team, name the team: "The support team reviews tickets daily."
Use "you" for steps, not "we." Write "Select Save," not "Now we select Save."
Don't let "we" hide an owner. "We should update this page" leaves it to no one. Name who: "[Team or person] updates this page each quarter."
Why this differs from some style guides: Customer-facing guides, like Microsoft's, often avoid "we" because there it means the company talking at a customer. In internal docs, "we" includes the reader.
Customize (B5b): If you chose not to use "we," replace this subsection with: "Avoid 'we.' Name the team instead."
Your answer: B5b: not answered
Use active voice
The subject does the action in active voice. It's shorter and makes clear who does what.
Yes: The finance team approves all purchase requests.
No: All purchase requests are approved by the finance team.
Not sure which one you wrote? Try the zombie test. Add "by zombies" after the verb. If the sentence still makes sense, it's passive.
"All purchase requests are approved by zombies." Makes sense, so it's passive.
"The finance team approves by zombies all purchase requests." Nonsense, so it's active.
Passive voice is fine when the actor doesn't matter or is unknown: "The file was deleted."
Use present tense
Docs describe how things work now. Future tense makes readers wonder when it'll be true.
Yes: The report shows last month's totals.
No: The report will show last month's totals.
Use contractions
Common contractions (it's, you're, don't) sound friendly and natural. Avoid awkward ones like there'd, it'll, and they'd.
For warnings where a missed word could cause harm, spell it out: "Do not delete this folder."
Customize (B6): If you chose no contractions, replace this subsection with: "Spell out contractions (do not, you will)."
Your answer: B6: not answered
Use gender-neutral language
When you don't know someone's gender, use "they," or rewrite with "you" or a role ("the requester"). See §08 for more.
Spelling and word choice
[Company] is always written exactly this way. Not: [common mistakes from A1].
Use US English spelling. Check Merriam-Webster, and use the first spelling it lists.
No fuzzy standards. If a rule says "reputable," "appropriate," "sparingly," or "when needed," say who decides or how to tell. "Use callouts sparingly" leaves everyone guessing; "No more than one callout per section" doesn't.
Word list
Use the same word for the same thing, every time. When a new term comes up, suggest it to [guide owner, from A2], who adds it here (see §12).
Use
Not
Notes
email
e-mail
log in (verb), login (noun)
log-in
"Log in to the portal." "Your login expired."
set up (verb), setup (noun)
set-up
"Set up your account." "Finish the setup."
back up (verb), backup (noun)
back-up
"Back up your files." "Restore from the backup."
check out (verb), checkout (noun)
check-out
"Check out the new dashboard." "Go to checkout."
allowlist, blocklist
whitelist, blacklist
See §08
[Your product or tool name]
[Common misspelling]
Customize (A1, B3, D2): Replace the starter rows with your own terms. Keep this list short and real. It grows best from actual questions.
Your answer: A1: not answered; A1b: not answered; B3: not answered; D2: not answered; D2b: not answered
Abbreviations and acronyms
Spell it out first. On first use, write the full term followed by the acronym in parentheses: "single sign-on (SSO)." After that, use the acronym.
Skip the spell-out for acronyms everyone knows better than the full term, like PDF, URL, and USB. If spelling it out would make readers stop and think ("universal serial bus?"), don't. A good sign: the acronym is in the dictionary.
Use only acronyms your readers know. If most readers would have to stop and think, spell it out.
Don't introduce an acronym you only use once.
Skip the possessive. Write "the API settings," not "the API's settings."
Don't start a heading with a new acronym. Define it in the text first.
Write out common Latin abbreviations. Use "for example" instead of e.g., "that is" instead of i.e., and "and so on" (or a complete list) instead of etc. They're easy to mix up and hard for readers who speak English as a second language.
Acronym
Meaning
Spell out on first use?
API
application programming interface
Yes
FAQ
frequently asked questions
No
PDF
Portable Document Format
No
SSO
single sign-on
Yes
TLS
Transport Layer Security
Yes
UI
user interface
Yes
URL
uniform resource locator
No
VPN
virtual private network
Yes
[Your acronym]
[What it means]
[Yes or no]
Customize (A1, B1): Replace these with your team's acronyms, especially internal ones (team names, project code names, tool nicknames). Set the last column based on your readers: a developer team may never need "API" spelled out. New hires will thank you.
Your answer: A1: not answered; A1b: not answered; B1: not answered; B1b: not answered; B1c: not answered; B1d: not answered
Punctuation
Punctuation isn't noticeable when it's done right. But when it's done wrong, it can change the meaning.
Let's eat, Grandma.
Let's eat Grandma.
This is a classic example of a comma placement to die for.
In a list of three or more, put a comma before the last item (the serial comma, also called the Oxford comma): "docs, slides, and spreadsheets."
When two words work together to describe a noun, hyphenate them (a compound modifier): "a high-quality image." No hyphen when they come after the noun: "the image is high quality."
Use an en dash (–) for ranges: "pages 5–10," "9:00 AM–5:00 PM." It's a little longer than a hyphen.
Mac: Option + hyphen
Windows: Alt + 0150 (on the number pad)
HTML or Markdown:–
Use em dashes (—) with no spaces, and no more than one per paragraph. A comma, colon, or parentheses usually work better.
Mac: Option + Shift + hyphen
Windows: Alt + 0151 (on the number pad)
HTML or Markdown:—
Put periods and commas inside quotation marks.
Yes: Call it "the dashboard."
No: Call it "the dashboard".
Use semicolons rarely. If a period works, use a period. Two short sentences are usually clearer than one long one.
Instead of: The team worked on the project for months; it's finally ready to present.
Try: The team worked on the project for months. It's finally ready to present.
Skip exclamation points in most docs. Save them for real excitement, like a launch announcement.
Customize (C3, C5, B3): If you chose no serial comma, update the first rule. If you chose hyphens ("5-10") or words ("5 to 10") for ranges, replace the en dash rule. In UK English, punctuation goes outside the quotation marks unless it's part of the quote.
Your answer: B3: not answered; C3: not answered; C5: not answered; C5b: not answered; C5c: not answered
Numbers and units
Technical values are always numerals: version numbers, measurements, pixels, ports, error codes, numbers in the UI, and anything the reader types. Put a space before a unit: "5 GB," "3 inches," "16 px."
For everyday counts in sentences, spell out zero through nine and use numerals for 10 and up: "five steps," "15 users."
Spell out a number that starts a sentence, or rewrite the sentence so it doesn't start with one.
Use commas in numbers with four or more digits: "1,000," "25,000." Except years, ports, version numbers, and codes: "2026," "port 8080."
Units we use often: [list from C5, for example GB, MB, px].
Customize (C5): If you chose Chicago's rule, change the everyday-counts bullet to "spell out one through one hundred." If you chose always numerals, delete that bullet.
Your answer: C5: not answered; C5b: not answered; C5c: not answered
Dates and times
Write dates as month, day, year, with the month spelled out: November 13, 2026. Don't use ordinals like "November 13th."
Avoid all-number dates like 11/12/2026 in running text. Readers in different countries read them differently.
Times: 3:00 PM. Use "noon" and "midnight," not "12:00 noon."
Time zones: Always include one for meetings and deadlines: "3:00 PM ET." For global teams, use Coordinated Universal Time (UTC).
Customize (C6): Swap in your date format, 12- or 24-hour time, and default time zone.
Your answer: C6: not answered; C6b: not answered; C6c: not answered
Citations and sources
When you borrow from another source, credit it. In most internal docs, a link is enough.
Internal docs feel private, so people paste things they shouldn't. But internal docs get shared, exported, screenshotted, and searched. Treat every doc like it could leave the building.
Never put these in docs
Passwords, API keys, tokens, and other credentials
[Customer names and data]
[Employee personal information, like personal email addresses, home addresses, and phone numbers]
[Financial account details]
[Health information]
[Security details, like server names, IP addresses, and internal URLs]
[Unreleased product or business plans]
Customize (D3): Keep the items you checked in D3. Credentials always stay on the list.
Your answer: D3: not answered; D3b: not answered; D3c: not answered; D3d: not answered
Point to it instead
Tell readers where to find sensitive information without including it:
Yes: Get the admin password from the "Payroll admin" entry in [password manager].
No: The admin password is Summer2026!
Where it lives: [password manager or secure location, from D3]
Questions about where something should live? Ask [contact, from D3].
Use placeholders in examples
Credentials:YOUR_API_KEY, your-password-here
Websites and email: example.com, name@example.com (these domains are reserved for examples)
Phone numbers: 555-0100 through 555-0199 (reserved for fictional use in the US)
People: made-up names, never real customers or coworkers
Check screenshots before you share
Blur or crop names, email addresses, account numbers, and anything else on the list above. Also check the edges of the screen: browser tabs, bookmarks, and notifications can give away more than you think.
Labels and legal requirements
Label confidential docs: [required notice from D4, for example "Confidential: Internal use only"]
Our requirements: [privacy laws, regulations, or audits from D4]
Not sure? Ask [legal or compliance contact] before you publish.
Customize (D4): Add your required labels and legal requirements. If none apply, delete this subsection.
Your answer: D4: not answered; D4b: not answered
If something sensitive gets posted
Tell [contact, from D3] right away.
Remove it, but don't assume that's enough. Page history, search indexes, and notifications can keep a copy.
If it was a password or key, change it. Once a secret has been posted, treat it as public.
Coming later
These sections are planned for a later version of this guide:
Document Types & Templates
Accessibility
Inclusive Language
Writing for Non-Native English Readers
Using AI Writing Tools
Contributing, Review & Maintenance
Resources
Generated with Style guide builder for internal documentation by Katrina Moody (katrinamoody.com). Template licensed CC BY-SA 4.0.
