Blog style guide
Guidelines for writing, formatting, and publishing posts on the Good Docs Project’s blog.
The blog is where the Good Docs Project community and guest authors can share their thoughts about good documentation. We will share posts that focus on best practices, open-source writing workflows, and project updates. This guide exists so every post feels like it belongs on our blog, no matter who wrote it.
If something isn’t covered, default to the Google Developer Documentation Style Guide, which we treat as our upstream reference.
This guide is for the blog only. For the template contributing guide, see the contributing guide in our GitLab repo.
The blog audience
We’re writing for documentation-adjacent professionals. Folks that are interested and want to create documentation for a project or product but might not be professional technical writers.
Our readers come from a wide range of fields: business, non-profit, scientific, academic, and open source. Some are looking for practical self-help; others are simply curious about documentation and open to learning more.
Experience level
Write for someone new to the field. Assume they’re a capable adult who just hasn’t encountered this stuff before. Start from first principles. Don’t assume they know the tools, the jargon, or the workflows.
That said, entry-level doesn’t mean condescending. A reader might be a senior scientist or a seasoned manager who’s never written a README. Respect what they already know.
Reader attitudes
People arrive with all kinds of attitudes.
-
Some are genuinely excited and want a framework they can use tomorrow.
-
Some are skeptical. They’ve heard docs matter but aren’t sold yet.
-
Some are reluctant. This feels like extra work on top of their actual job.
Write for all three. Don’t assume the reader already cares. Make the case, show the value, and don’t make them feel bad for not being a believer yet.
Content focus
Posts should leave readers with something concrete. A technique to try, a concept that clicks, a perspective that changes how they think about docs.
Most posts will fall into one of these subject categories.
-
How to write good docs. The core of the blog. Practical guidance on structure, clarity, style, and specific doc types (READMEs, knowledge bases, support tickets, and more).
-
Docs advocacy. Making the case for documentation, why it matters, how to get buy-in, how to build a docs culture on a team that doesn’t have one yet.
-
The state of technical writing. Trends, tools, and where the field is heading. This is not a primary focus for the blog. We will only consider a post when there’s something genuinely new to say.
The posts could follow one (but not limited to) the following structures:
| Type | Purpose |
|---|---|
Tutorial |
Walk readers through a task step by step. |
How-to guide |
Answer a specific “how do I…” question. Less hand-holding than a tutorial. |
Community spotlight |
Profile a contributor, project, or case study. |
Announcement |
Share a release, event, or major update. |
Opinion / perspective |
A well-reasoned point of view on a docs topic. |
Think business casual. A knowledgeable colleague who takes the subject seriously but doesn’t take themselves too seriously. Not a corporate manual, not a casual chat. Somewhere confidently in between.
What that looks like in practice
-
Friendly and approachable. Warm without being gushy.
-
Confident. We know this material, so write like it. Hedging everything just makes the reader doubt you.
-
Not condescending. Readers are competent people learning something new. Treat them that way.
-
Direct. Get to the point.
-
Honest. Acknowledge tradeoffs. Don’t pretend documentation is always easy or always worth it.
-
Inclusive. Write for a global audience. Skip the idioms.
Tone by article type
Tutorials and how-to guides can be a bit warmer and more conversational. Opinion pieces can lean into first person, but stay grounded in evidence.
✅ “You can configure the linter in three ways. The simplest is…”
❌ “The user must configure the linter. There exist three configuration methodologies.”
✅ “This step is tricky, so take your time.”
❌ “This is easy. Simply run the command.”
AI and technology
AI is part of the documentation landscape and we’re not going to pretend otherwise. Posts about AI tools, AI-assisted writing, and what AI means for technical writing are welcome, but they’re not the focus of this blog, and no single view on AI is the official position of The Good Docs Project.
A wide range of views is welcome. Skeptical, enthusiastic, cautious, pragmatic.
If you write about AI, be specific. What tool, what task, what outcome. Broad claims about the technology don’t give readers much to work with.
What is out of scope:
-
Posts that are broadly hostile to AI writing tools.
-
Posts that argue for removing humans from technical writing entirely.
Basic post structure
The following provides a basic structure for a post.
Title (required)
Use sentence case. Capitalize the first word and proper nouns, nothing else.
Tell the reader exactly what they’ll get. Keep it under 60 characters so it doesn’t get cut off in search results and social shares.
✅ “How to write alt text for documentation screenshots”
❌ “Alt Text: A Complete Guide to Accessibility in Technical Writing and Beyond”
Introduction (required)
Within the first two or three sentences, say what the post covers and who it’s for. Readers are scanning to decide whether to keep going. Don’t make them hunt for it.
Body (required)
Use H2s for major sections, H3s for subsections. Don’t skip heading levels. Each section should make enough sense on its own that someone could jump in without reading everything before it.
Additional style tips
The following provides additional style tips to consider when you are writing a blog post.
Bulleted lists
Use bullet lists when order doesn’t matter and there are three or more items. Two items usually work fine as a sentence.
Use numbered lists for steps where order matters.
Either way.
-
Start each item with a capital letter.
-
Be consistent with punctuation. If one item ends with a period, they all should.
-
Keep items parallel in structure (all verbs, all nouns, etc.).
-
Don’t nest more than two levels deep. If you’re nesting a lot, consider restructuring into sections.
Links
Make your link text do some work. It should tell readers where they’re going, not just that there’s a link. Please avoid using “Click here” for link titles.
✅ “See the contributor guide for setup instructions.”
❌ “Click here for the contributor guide.”
Don’t use raw URLs as link text unless the URL itself is the point.
Only open external links in a new tab when leaving mid-process would actually be disruptive.
Check that links work before submitting.
Don’t link the same destination more than three times in one post. Link it once prominently, then just reference it by name.
Prefer plain language
Use the simpler word. Readers are often working in a second language, working quickly, or both.
| Instead of | Write |
|---|---|
utilize |
use |
in order to |
to |
leverage |
use |
prior to |
before |
it is important to note that |
(just say the thing) |
simply / just / easy |
(cut it, it minimizes real complexity) |
Inclusive language
-
Use they/them as a singular pronoun, not “he or she.”
-
Avoid violence metaphors where there’s a reasonable alternative (“stop the process” instead of “kill the process”).
-
Use allowlist / denylist instead of whitelist / blacklist.
-
Refer to roles, not demographics.
Tense and person
Write in present tense. Use "you" to address the reader. Use we when speaking for the project.
When to use bold, italics and underlining
Bold UI labels, key terms on first introduction, genuinely critical warnings. Not decoration. If everything’s bold, nothing is.
Italic Titles of works, introducing a term you’re about to define, occasional light emphasis. Use sparingly.
Avoid underlining. Underlined text that isn’t a link confuses people.
No ALL CAPS. Use bold if you need emphasis.
Next steps
That’s everything you need to get started. Good documentation takes practice, and every post you write helps the community grow. We’re glad you’re here, and we can’t wait to read what you write!
The Good Docs Project Blog Style Guide, maintained by the community. Upstream reference, Google Developer Documentation Style Guide.