5 technical writing foundations for exceptional dev docs

I've been writing technical documentation for web developers and security engineers for half a decade and I know that writing error-proof documentation is challenging.

You're not just writing explanations, you are guiding someone through a new, often unfamiliar, workflow without friction.

Even with the popularity of other useful learning tools, like video or LLMs, the docs remain powerful in their position as the source of truth on product knowledge and can be a make-or-break decision factor in purchasing decisions.

Whether you’re writing your first draft or refining with AI, these tips will help you communicate your instructions clearly and effectively. 

1. Replace vague ‘it’ and ‘this’ pronouns with specific, named terms

Your users do not know your acronyms, your tools, your features, or your products like you do. Users do not know how all these components interconnect with each other. To prevent users from wasting time rereading and deciphering instructions, make your text precise and unambiguous by naming the thing you are referring to.

Let’s review the following example: 

As a user, I am doing the guesswork to figure out what ‘it’ and ‘this’ mean in this paragraph.

As a writer, if I change this passage to include specificity:

I have left my users no room for error.

Let’s look at another example:

Let’s replace ‘it’ and ‘this’ with the name of the thing itself:

If you feel like you are repeating your product name or concept five times in a paragraph, good! You’re writing an error-proof manual.

My recommendation: write your first draft in flow, don’t go back to edit anything and focus on getting the words out of your head and onto the page. Writing and editing are two separate processes and work best when respected as such. When you switch to editing mode after writing your first draft, review your draft for ambiguous references (it, this, that, these) and replace them with specific, named terms.

2. Assume every page is the user’s first touch (so add inline links and a glossary)

To keep your user empathy muscle working against the trap of assumptions, assume every page in the docs is your user’s first encounter with your product.

Let’s demonstrate this methodology with a common scenario. You have a product named Simple Writing Intelligence Tool (SWIT, for short). You are working on a third-party integration guide with SWIT.

You or your stakeholders may have a list of assumptions about the users reading this guide:

Assumption: “It’s an integration guide, not a getting started, so the user must already be familiar with SWIT.”

Reality: The user might be familiar with the third-party tool and found SWIT as a consequence of the integration. By assuming knowledge, we’re limiting the audience we’re writing for and alienating potential users.

Best practice: Links. To reduce page size, link out to the SWIT conceptual or “Getting Started” docs to introduce your product. If you’re introducing a CLI command, API, or an industry term, link out to the appropriate documentation that goes into those ideas in detail.

-

Assumption: “My users are highly technical, they don’t need handholding on the concepts behind this integration.”

Reality: User data reveals again and again that the opposite is true. Readers want unassuming, unambiguous instructions, no matter their level of experience in the industry. “Highly technical” doesn’t mean users want to spend the time reverse engineering incomplete instructions, especially when they are under deadline or debugging a problem.

Best practice: Standardize your terms. Use consistent language for your product and feature definitions and organize those definitions in a glossary you can refer users to. If you’re introducing an industry concept (like What is technical writing?) rather than something you built, find and link to a reputable source to introduce the concept.

-

Assumption: “I don’t want to repeat myself. The user has read the prerequisites and knows what to do.”

Reality: Users do not read chronologically. They jump around, skim, or land mid-page from a search engine or shared link.

Best practice: Links (again). If step 7 depends on something from step 2, link directly to step 2 within the step 7 instructions. This avoids unnecessary repetition while guiding users to what they need, reducing the chance of missed context or error.

3. Summarize the user’s goals and accomplishments

Your instructions should answer four essential questions: 'What?', 'How?', 'Where?', and 'Why?' 

• What am I doing?

• How am I doing it?

• Where am I doing it (CLI, dashboard, mystery third place)? 

• Why am I doing it?

A strong introduction includes the goal of the instructions and the expected outcome. A strong conclusion summarizes the user’s achievements and expected results.

But this philosophy doesn’t just apply to intros and outros, you can apply it to each step. Here’s a comparison to show why that matters.

The following example is the final step of a guide:

And now the same instructions, written with the four essentials in mind:

In the second example, we have answered:

• What is happening? You’re deploying a project.

• How is it done? By running the abc deploy command.

• Where is it happening? In your project directory, via the CLI.

• Why does it matter? Because this is the final step that takes your project live.

When you consistently anchor your instructions in what, how, where, and why, your users stay oriented, confident, and on track at every step.

4. Remember your global users

I believe California English has become a global standard for the way we communicate using English. This is because of two major socioeconomic influences: Hollywood and Silicon Valley. The world feels familiar to people who speak California English, and the assumption that it feels familiar to everyone else can be a point of disconnection.

I grew up in LA, but I worked in Korea in self-taught Korean for almost 3 years. I wrote emails in Korean, presented in Korean, spoke to senior leaders in Korean, got scolded and celebrated in Korean, and did nuance in Korean. It was my third language, and every day, it took mental energy to be able to work in it.

This has given me the capacity to empathize with users in ways many people overlook. When I write documentation, I think about the mental load users are carrying to take in information in another language and take action. I want users to be successful, and that means they are energized by my writing to take action.

So I avoid these pitfalls when writing docs:

- Run-on sentences: A sentence should be no longer than 14 words. Simplicity of expression is not the same the same thing as simplicity of concept. You should always be aiming to describe hard things with ease. Respect your reader's mental energy.

- Colloquialisms: I know we do this in tech. "Under the hood", "out of the box", some of these terms have become so commonplace it may seem obvious or easily Google-able. But customers understand concepts best when the concepts are described with technical details: what does the thing actually do? Answer this question and leave the storytelling for the blogs.

5. Know your user journey

Mapping out what knowledge makes the user successful at each step of the product journey will make your docs cohesive and effective.

One of the best ways to get crystal clear on that product journey is by aligning with your product specialists, such as the product manager, engineering lead, or a dev advocate. A simple product journey mapping session focuses on the details of these three stages:

1. Before Stage (What prerequisite knowledge or access does the user need before they start?)

2. During Stage (What steps does the user take to configure and deploy the product?)

3. After Stage (How does the user assess success, and what are the maintenance guidelines or next steps?)

Let’s say you are mapping the configuration step with your team. One teammate’s step-by-step assumptions about configuration may look like this: 

• User creates an account.

• User installs the CLI tool.

• User authenticates using an API token.

• User configures environment variables.

• User runs the deployment command.

• User checks logs and sets alerts.

But another team member might map the user journey differently:

• User authenticates using an API token.

• User configures environment variables.

• User sets the deployment region.

• User runs the deployment command.

• User checks logs and sets alerts.

The second team member has assumed the user already installed the CLI tool, and that the user knows how to use the CLI to configure environment variables and deploy. The second team member also added “set the deployment region” as a step.

If you ask your product stakeholders to list the steps of a “Get Started” guide they want users to follow, they are likely all going to write something different. And that’s good! Combine all those steps, and you’ll be able to produce an error-proof experience in your docs.

Mapping your users' steps and the knowledge they need at each step will help you write thorough prerequisites, thorough instructions, and successful guides.

Great documentation doesn’t just explain how something works; it empowers the reader to complete their task with confidence. When docs are consistent and clear, they become accessible to a larger reader base and turn users into successful problem solvers.

I hope these fundamental best practices can help you turn complexity into clarity for every user, every time.