# Style guide for technical writing: what to include and how to build one

> Learn how to create a technical writing style guide that keeps developer docs consistent, covers API conventions, and streamlines reviews and maintenance.

**Source:** https://hackmamba.io/technical-writing/style-guide-for-technical-writing/
**Published:** 28 Aug 2026
**Author:** Asjad Khan
**Category:** Technical writing

---
A style guide is the agreement between your writers, editors, and reviewers on what good looks like. It settles the questions that would otherwise be re-argued in every review, so the team can focus on whether the docs are correct and clear. Without one, a review thread stalls over whether a heading should use a capital letter.

We build and maintain these guides across live devtools clients, and the pattern holds across the board. The teams that struggle are not short on talent. They are short on a shared answer to a hundred small questions, and those questions surface one pull request at a time until someone writes the answers down.

## **Why teams end up needing one**
The trigger is almost always the second writer. One person writing docs carries the whole style in their head, and it stays consistent because it lives in one place. Add a second writer, then a third, then an engineer who contributes a page. The same UI element appears capitalized in three different ways across three pages that shipped the same week.

The cost shows up in the review. Without a guide, review threads fill with debates about sentence case versus title case, whether to write "sign in" or "log in," and how to format a placeholder. [Google's own technical writing team](https://developers.google.com/tech-writing/resources) names this directly, calling heading-style arguments a waste of time and energy that a single adopted guide removes.

We see the same thing on client doc sets. When several writers touch the same product across weeks, small inconsistencies compound into a documentation set that reads like it was written by a committee, because it was. A style guide is the fix, and the smallest useful version is smaller than teams expect.

## **What a style guide should include**
Here is the counterintuitive part. A guide that survives is not one you write from scratch, and you do not write the whole thing yourself. [Google's guidance is blunt](https://developers.google.com/tech-writing/resources): teams should not write their own editorial style guide because a house style guide requires tremendous resources and causes conflict.

Adopt an existing technical editorial guide as your base, then layer only what is specific to your product on top. That base is either the Google Developer Documentation Style Guide or the Microsoft Writing Style Guide, both designed for technical content and free to adopt.

Your own layer answers the questions the base guide cannot: those specific to your product, your terms, and your voice. Google [states the resolution order plainly](https://developers.google.com/style/): project-specific style takes precedence, followed by the adopted guide, then a third-party reference such as the Chicago Manual of Style. Everything below belongs in your layer, and each item earns its place by settling a recurring argument.

**Voice and tone** come first because they are the hardest to standardize and the easiest to feel when they are missing. State the default and name the exceptions. For most developer docs, the default is second person, active voice, and present tense, which is what Google recommends for instructions that need to feel direct. The exceptions matter as much as the rule, so say when a warmer register is allowed and when it is not.

**Terminology and a word list** are the highest-friction items to leave out. This is the definitive list of your product terms, their preferred spellings, and the alternatives nobody should use. It answers whether your feature is a "workspace" or a "project," whether "webhook" takes a hyphen, and which internal names never appear in public docs.

[Mailchimp keeps a running](https://styleguide.mailchimp.com/grammar-and-mechanics/) list of terms it capitalizes and those it doesn't, which is the model to follow. For recurring wording and explanation patterns that accompany a word list, our technical writing glossary collects the ones we rely on.

A word list can start as three columns and grow from there. This is an illustrative shape:

| Use | Avoid | Note |
| --- | --- | --- |
| sign in (verb), sign-in (noun) | login, log in | Match the product UI |
| API key | api key, APIKey | Two words, uppercase API |
| self-hosted | self hosted, selfhosted | Hyphenated in all uses |


![Mailchimp's public word list](https://s3.eu-west-2.amazonaws.com/growth-hackmamba-w2n1/1787833856135-Word-List-Mailchimp-Content-Style-Guide-08-27-2026-06-00-PM.png)
**Formatting for code and UI elements** settles how technical content is presented consistently across all pages. Decide how inline code, code blocks, placeholders, and UI labels get written and capitalized, then stick to it.

A reader learns to trust that bold means a button and code font means something they type. [Google puts code-related text in code font and UI elements in bold](https://developers.google.com/style/highlights), which is the clean default that earns that trust, and the trust holds only when the formatting stays consistent across every page.

**Headings and structure** cover the capitalization rule, the heading hierarchy, and one habit worth enforcing. Pick sentence case or title case and stop discussing it, since the choice matters far less than the consistency. The habit is to write headings that state an outcome rather than a topic, so "Authenticate a request" beats "Authentication" because a reader scanning the page can find the task they came to do.

**Punctuation and capitalization** are where the low-value arguments live, so settle them once. The Oxford comma, how list items are punctuated, and how product names are capitalized are the recurring three, and a single ruling on each ends the debate for good. None of these choices is important on its own. What matters is making the choice and writing it down so it stops coming back.

**Abbreviations and acronyms** need one rule and one definition. The rule is to expand on first use, and the definition is what "first use" means, whether that resets per page or holds across a whole doc set. Get specific here, because "spell it out the first time" falls apart the moment a reader lands on page four from a search result with no memory of page one.

**Inclusive and accessible language** belongs in every modern guide, and it needs concrete replacements, not a principle. Give the actual swaps: the singular "they" when a person's pronoun is unknown, alt text on every meaningful image, link text that describes its destination instead of "click here."

[Mailchimp's guide is a strong reference here](https://styleguide.mailchimp.com/), with specific person-first guidance in place of a vague call to be inclusive. This is not optional, and writing it down is what turns intent into practice.

Those seven items cover most of the documentation, and the next section adds the layer that they do not reach. Developer and API docs need everything above, plus conventions that the general items never touch.

## **What is different in the API and the developer documentation**
API and developer documentation use the same guide, with an API-reference layer on top. It does not need a guide of its own. The base rules on voice and terminology still apply, and a handful of reference-specific conventions are added. This is the layer where our work concentrates, and it is where a general writing guide runs out of answers.

Code sample conventions come first. Decide the languages you support, whether samples are runnable or illustrative, and how they are formatted, then apply them uniformly.

[Google's guide is specific](https://developers.google.com/style/code-samples), recommending a short sample of roughly five to twenty lines at the top of each reference page and wrapping lines at a set width. A reader should be able to tell at a glance whether a block is something they can run or something that shows shape.

Placeholder styling is small and constantly gotten wrong. Pick one convention for the values a reader has to replace and use it everywhere, so `YOUR_API_KEY`, `<project-id>`, and `{variable}` do not all appear across different pages for the same idea.

The point is that a reader learns your placeholder shape once and recognizes it everywhere after. Inconsistent placeholders make a reader wonder whether the difference means something, which is the doubt good docs remove.

Here is the before and after. The first block mixes three conventions for the same idea across pages:

```plaintext
curl -H "Authorization: Bearer YOUR_API_KEY"
curl -H "Authorization: Bearer <api-key>"
curl -H "Authorization: Bearer {apiKey}"
```

Use one convention everywhere. [Google's guide settles on uppercase with underscore delimiters](https://developers.google.com/style/placeholders), like `API_KEY` and `PROJECT_ID`, and explains each placeholder the first time it appears:

```plaintext
curl -H "Authorization: Bearer API_KEY"
```

The specific shape matters less than the consistency. [Cloudflare's public guide uses angle brackets instead](https://developers.cloudflare.com/style-guide/formatting/code-conventions-and-format/), like `<YOUR_DOMAIN>`, and that works as well because it adheres to a single format.

Parameter and endpoint naming conventions have to stay in sync with the actual API, which is the hard part. The guide should explain how parameters are described, what each one serves, what their expected values are, and how the docs stay aligned as the API changes.

[Google's reference rules](https://developers.google.com/style/api-reference-comments) ask for a description of every class, method, and parameter, including behavior for booleans and defaults. Apply that with judgment, because, taken literally, it produces pages of redundant "the id is the id" entries; the rule is a floor for coverage, not a license to pad.

Versioning language is the convention teams remember last and need most. Decide how the docs mark deprecated endpoints, how breaking changes are flagged, and where migration notes live.

A reader who lands on a page for a version they are not running needs to know that in the first line, before they copy a call that no longer works. This is the reference layer that most often falls out of date, so the guide should tie a docs update to the release itself.

All of this only holds if someone keeps the guide up to date. A guide that covers the right things still fails if it drifts from the product, which is a question of ownership rather than of content.

## **Who owns it and how it stays current**
A style guide that nobody owns goes stale. A stale guide is worse than none, because people follow it and end up wrong. Ownership does not mean one person writes every rule. It means one person or team decides what goes in, reviews proposed changes, and keeps the guide honest as the product moves.

Where the guide lives determines whether it stays alive. Keep it in the same repository as the docs, in plain text or Markdown, so a change to the guide moves through the same pull request and review flow as a change to the docs. When the guide sits in a separate wiki that nobody opens, it drifts from what the team does in practice, and writers fall back to copying whatever the last page did. Proximity to the work is what keeps it current.

Updates should arrive the way code does, as a proposal others can see and discuss. A writer hits a question the guide does not answer, opens a change with the proposed ruling, and the owner merges it once there is agreement. That record matters later because the guide then explains the rule and its rationale, which prevents the same debate from reopening in six months.

The guide works alongside the other documents a writer starts with, such as the [content brief](https://hackmamba.io/technical-writing/content-brief-for-technical-writers-template/) that sets the scope before drafting begins.

Enforcement works best when it is partly automatic. [A linter like Vale](https://buildwithfern.com/post/api-documentation-platforms-style-guide-enforcement) can check drafts against your adopted base guide and your own terminology in the same continuous integration run that tests the code, so terminology slips and passive-voice violations get flagged before review.

![Vale Output](https://s3.eu-west-2.amazonaws.com/growth-hackmamba-w2n1/1787834239593-Screenshot-2026-08-27-at-6.06.38-PM.png)

The machine catches the mechanical rules, which frees human review for the judgment calls a linter cannot make. We cover the wider toolchain we use in [our writeup on AI tools for technical writing](https://hackmamba.io/technical-writing/ai-tools-for-technical-writing/).

The clearest way to see all of this working is in guides that are already public. Three are worth studying closely, each for a different reason.

## **Three examples worth studying**
You do not need ten examples to build a good guide. Two or three studied closely teach more than a long list skimmed, and these are the three we return to most.

The [Google developer documentation style guide](https://developers.google.com/style/) is the clearest example of a guide built for technical and API documentation rather than general writing. It is public, free to adopt, and specific where it counts, with dedicated pages on code samples, API reference descriptions, and UI element formatting.

![Google Dev Documentation Guidelines](https://s3.eu-west-2.amazonaws.com/growth-hackmamba-w2n1/1787834365412-Code-samples-Google-developer-documentation-style-guide-Google-for-Developers-08-27-2026-06-08-PM.png)

The Google guide is the strongest candidate for the base you adopt rather than rebuild, which is the main reason it is worth studying.

Stripe is worth studying for how a devtools company holds consistency across a large docs surface without publishing a rulebook. Stripe encodes its style through conventions and tooling, defining a term in a single inline sentence the first time it appears, so a reader never has to leave the page, and keeping the code column populated on every reference view.

Stripe also [open-sourced Markdoc](https://stripe.dev/blog/markdoc), the framework it uses to author docs in, which is how the conventions get enforced at the tooling level. The lesson is that a style can live in culture and tooling as much as in a written document.

The [Mailchimp content style guide](https://styleguide.mailchimp.com/) is the strongest public example of voice and tone guidance, and it is openly licensed for reuse with attribution. It is organized by content type, with concrete rules on active voice, plain language, and person-first writing in place of vague principles.

It is a content and brand guide rather than a developer-doc guide, which makes it the right model for the voice layer specifically, paired with a technical base like Google's for everything else.

## **Conclusion**
A good style guide is smaller than teams expect and easier to maintain than people assume. Adopt a technical base guide, layer your own voice, terminology, and reference conventions on top, give it an owner and a home in the docs repo, and let a linter handle the mechanical checks. The goal is not a document that covers everything. It is a shared answer to the questions your team keeps asking, written down once so the work can move on.

## **Frequently asked questions**

1, **What should a technical writing style guide include?**

At minimum, it should cover voice and tone, product terminology and word list, formatting for code and UI elements, heading and structure rules, punctuation and capitalization, acronym handling, and inclusive language. For developer docs, add an API reference layer with code samples, placeholders, parameter descriptions, and versioning. Most of this can sit atop an adopted base guide rather than being written from scratch.

2, **How detailed should a style guide be?**

Detailed enough to settle the arguments your team keeps having, and no more. A guide that tries to rule on everything becomes too long to maintain and too long to read, so it goes stale. Start with the recurring friction points, adopt a base guide for the rest, and add rules as real questions come up.

3, **Should API documentation follow a different style guide?**

API documentation should follow the same guide, with an added reference layer. The base rules on voice, terminology, and formatting still apply to API docs, and on top of them, you add conventions for code samples, placeholders, parameter descriptions, and versioning. A separate guide would only duplicate the shared rules and cause them to drift out of sync.

4, **Who owns and updates a style guide?**

One person or team should own it, deciding what goes in and reviewing proposed changes, even though anyone can propose an addition. The guide should live in the same repository as the docs, so updates move through the same review flow, and it stays current when changes arrive as visible proposals rather than private edits. Ownership without a home in the workflow is where most guides go stale.

5, **What is the difference between a style guide and an editorial guide?**

The terms overlap, though they are not identical. In this article, the style guide means the rules for writing itself, covering grammar, voice, terminology, and formatting. Editorial guide is the broader term, and it can also cover process standards like how content is planned, reviewed, and published, so a style guide is one part of it.