Tech writing is fundamentally about helping people understand concepts that are potentially complex or new to them. To do this effectively, before you start putting fingers to keys, you need to start by asking three key questions about your subject and the audience(s) for it. After doing this, later and more in-depth parts of the process will become clearer and easier. There are more audiences for your words than you might think, and different audiences have different expectations and needs from documentation. Understanding these will save you hours of work and countless frustrations later. Finally, to help you through those frustrating times, I hope to help you understand how important good tech writing is and what a crucial role you play, whatever the nature of your work is.

This chapter covers the following main topics:

• Why tech writing is important
• What documentarians can accomplish
• How to understand who you are writing for

What’s one of the first things you look at when evaluating a new project or service? If the documentation isn’t the first thing you look at, I bet it’s in the top three. The primary function of documentation is to tell people how to use something, but it also has several crucial secondary purposes that provide value across a company or project team.

To quote a phrase I’ve used for a while in presentations:

“Documentation isn’t just for developers.”

Documentation gives confidence in a product making it useful for marketing sales enablement, customer support, search engine optimization (SEO), and, as we now realize, for myriad other machine-driven purposes.

This section reinforced what you probably already know and feel. After all, you’re reading this book! But how can you convince others of the worth of good documentation?

Tech writing often sits between and crosses over multiple teams in a company or project. This means that you have the potential to impact the work and goals of many, even if it’s not in your initial job description. This section covers some of the most common teams and departments you might encounter.

Marketing

If a project’s documentation is open to the public (not behind a login), it likely fuels a high percentage of searchable text on a website. High-quality, well-written documentation optimized for SEO is a goldmine for search engine traffic. No one wants to read documentation stuffed full of marketing content and working closely with a marketing team to ensure style consistency and break down content silos is essential.

Depending on the size and structure of your company or team, documentarians and marketing teams can work closely together to help this process. You can collaborate on style guides, write technical blog posts, review or edit white papers, and so on.

Product

I’m sure many of you know that good documentation can’t hide or improve a bad product. However, for the most part, products and documentation are somewhere between fantastic and terrible. Good documentation brings confidence in a product to a potential customer or user. Later chapters in this book will describe how to make your writing more confident, and this is one of the justifications for that style of writing. Often, someone decides between product options by reading their documentation. The products that sound confident and can do what their documentation promises are likely to appeal more to potential users.

Sales

Sales and sales engineers often have some of their own playbooks and content for working with current and future customers. However, much like with marketing teams, documentarians can work closely with them to ensure materials are consistent and break down those omnipresent content silos.

Support

Customer success, support, or whatever a company calls the team of people who help users achieve their goals are often any documentation team’s biggest allies and sources of knowledge. They see how people try to use a product daily. They know where users struggle, what they find confusing, and the common pitfalls they face. These teams also likely maintain their own sources of information or documentation. Again, try to work with them to reduce these silos, but regularly syncing with them gives you a great source of information for what documentation is missing and how effective current documentation is.

Developer relations

Though they are often part of sales or marketing teams, developer relations teams are typically out speaking with developers, convincing them, and helping them use a product. The content they produce could be one of the first things that a potential user sees, so again, work with them to ensure consistency of message, reduce silos, and much like support, find out what they feel is missing from the documentation that would help users.

Engineering

Fundamentally, documentation exists to make what product teams created understandable. Or, as I like to say:

“Documentation makes engineering look good.”

If you’re reading this book, then you’re probably an engineer. So, I phrase this section slightly differently from the other teams’ sections. Documentarians need to get details from engineering to explain how a product works and how to use it. There is frequently a disconnect between what engineering thinks is important, what documentarians think is important, and what users think is important. I dig deeper into this topic throughout the book, but briefly, cast aside your assumptions and in-depth knowledge and think about how someone completely new perceives what you have built.

Machine readers

It may or may not surprise you that much of the traffic to your documentation probably doesn’t come from human readers. Website scrapers, sitemap builders, and a variety of other machines trawl your documentation regularly. While documentarians are typically aware of SEO, the implementation of best practices can vary. This is another perfect opportunity to work with marketing teams to improve the visibility of documentation and surface it to potential customers even more than it already is.

However, SEO and “traditional” crawlers are old news. The new machines trawling your documentation in great numbers are feeding training data for large language models (LLMs) (https://en.wikipedia.org/wiki/Large_language_model). Whether you like this or not, if your documentation is public and for a moderately high-profile product, then until we agree on a standard way to block this happening, it’s probably already too late. I cover the rapidly changing topic of artificial intelligence (AI) and documentation in greater detail later, but right now, be aware that an increasing amount of people are interacting with the words you write in myriad ways.

Proofreading for accuracy and safety

Unless my memory fails me, I have never worked documenting any “mission-critical” product. There were undoubtedly products that were very important to customers, and any downtime or poor information would impact their business. But typically, any product issues are covered by service-level agreements (SLAs) (https://en.wikipedia.org/wiki/Service-level_agreement), which don’t often cover documentation issues.

For the most part, if someone finds an error or inaccuracy, I can almost immediately fix it and roll out a new version. While that inaccuracy might have caused inconvenience, it’s unlikely to have caused a major loss of money, time, or life. Thankfully. However, I have met many documentarians working on projects and with toolchains that don’t allow this luxury or flexibility. I once met someone who created the documentation for rolling out Google’s data centers. They had to print all documentation as there was no internet access allowed, and if someone found an error, they had to print new copies. Any error – for example, an instruction to plug a cable into the wrong socket – could cost millions in revenue per day. I also met documentarians who work for Schindler. Again, their installation engineers receive hard copies of documentation, and installing an elevator or escalator incorrectly costs money and can cost lives.

Content silos

I mentioned content silos several times in previous sections. I have never worked at a company where these didn’t exist but keeping them in check is important. Regarding documentation and documentarians, the content other teams create is an excellent source of what’s missing from the documentation. I appreciate that documentation teams are often far outnumbered by other teams, and this is what causes these teams to create what they need in the first place. One of the aims of this chapter is to help you justify your role and, hopefully, grow its capacity. The fact that other teams are creating content that they feel is missing can be an effective justification for increasing documentarian capacity. It’s not the only reason other teams create what you can consider documentation (companies are full of politics, after all), but it’s one potential reason.

Writer in the middle

In summary, as you can hopefully see, documentarians and their work sit in the middle of many different roles and teams. This position comes with positives and negatives that are worth knowing. Even if you don’t intend to move into a full-time documentation role, it’s worth knowing what they could be, as, at the very least, it will help you empathize with those who are.

Even if you are one of the most level-headed people, gathering, processing, and acting on all these potential inputs is overwhelming. A documentarian can be such a fountain of knowledge, knowing a small to medium amount about numerous topics, that it can become frustrating to know what to do with all this knowledge. You might feel motivated to get involved in too many activities or try to fix too many things. Again, attempting this is overwhelming and, depending on your company, unwelcome. One of the biggest frustrations I have personally found as a long-term documentarian is that you often hear internally and externally that documentation is important. Reading this book, you probably already know and agree with this. However, the reality of the documentarian role is that you often don’t feel as important as everyone says you are. Some of this comes from expectations versus assumptions. Almost everyone has an opinion on when documentation is “wrong,” but fewer can tell you what they would do about it or when it is “right.” Documentation is front and center in nearly every product but is often created and crafted behind the scenes by people who like to think in the written word and don’t always speak up. Documentarians lack the kudos and credibility of programmers and engineers. They are often not in a position to push product ideas forward, yet they can tie all of these teams together.

Switching to the positives, while gathering and processing so much information can be overwhelming, it is also rewarding. Documentarians are often the first testers of a new product or feature, the first to find issues, and the first to follow a user workflow outside of a development team. If you enjoy exploring or figuring things out, creating documentation is an ideal role for you. You are often provided with a sketch or a draft of a product or feature and need to figure out in more detail how it works and how to explain it to an audience. In software documentation, this involves understanding a broad range of programming languages, frameworks, and techniques and learning how a user is likely to use those in a real-world scenario.

The most significant positive is knowing that, even though you may not always hear from them directly, your words will impact people as they try to accomplish their goals.

You’re in front of the keyboard, and an editor opens with a blinking cursor. You have a brief and have experimented with a prototype. Now comes the task of figuring out how to explain that prototype to different user groups and profiles.

While reducing a discussion to an acronym may sound like a cliché, I typically start by thinking of the three Ws:

• Who is reading a document?
• What do they want to accomplish?
• Why do they want to accomplish it?

Even if you haven’t addressed these Ws, other members of your company likely have, and you can leverage their work in yours.

Your product, project, or feature possibly has multiple user profiles, and the type of documentation you need to produce can vary for each one. Functional user profiles are easier to break down and analyze, as someone whose job involves task A is more likely interested in documents that describe how to undertake task A rather than B. The level of complexity and the content are more subtle than this, and you can make some general assumptions based on the type of document someone is reading (I will dig more into what these different document types can be later).

Someone reading API or reference documentation probably has an idea of something specific they want to understand and know the functional facts. Someone reading a quick start is probably newer to a project and would like an opinionated introduction. Reference documentation and a quick start guide are two reasonably clear ends of the documentation spectrum. In between is the tricky part and the part where you will spend the most time.

If you are documenting a simpler project or a project with a focused use case, then this task is easier than something more broad and general purpose.

I appreciate that, as with many technical topics, everything depends, and implementation relates to the use case. It’s usually easier to follow with an example that walks through a thought process instead of talking in abstractions. So, let’s move on to a practical example.

Learning by example

For example, a geocoding library has far fewer functions and applications than a database or a programming language. Guessing what someone might want to do with any general-purpose tool is challenging and will take a while to perfect. Let’s take an example project used throughout the book. I assume that you are working on a greenfield project, but many of the same principles apply if you work on a pre-existing project.

Monito is a tool for monitoring application performance and errors. Monito comes in two versions: a self-hosted version where you have to connect it to your own backend and analysis tools to gather, save, and analyze data, and a hosted version that plugs right into a data store and dashboard service.

My recommendation is to start with the beginning and end of the journey and slowly fill in the gaps over time. Monito has two starter paths. There’s only one of you documenting the project, and time is tight. So, which should you document? Chapter 5 covers the full documentation process. For now, you get a strong indication that as much as the project wants to support everyone’s choice of integration tools, documenting all those possibilities will take too much time right now. So, you decide to start with documenting the hosted version.

To get started with the hosted version, a user must choose a software development kit (SDK) in their application code. Again, Monito offers SDKs for many languages. User research shows that the most popular are JavaScript, Python, and Go. So for now, you decide only to show examples for those but mention that other options are available.

The user then needs to register an account for an SDK key that identifies them as the user and instantiate the SDK with that key, so you show how to do that with the three chosen SDKs.

Next, you show how to trigger key events using the SDK in the three languages and how they appear in the hosted dashboard.

Finally, you summarize what the guide covered and point people to the next steps.

That covers the quick start. What about the reference documentation? For now, as a lot of interaction with the service is via SDKs and the development team has stuck to well-established best practices while building the SDKs, you decide to stick with autogenerated documentation from the SDKs. This is enough for those who want to dig into what else is possible after following the quick start.

A week or two after release, you start receiving user feedback. More users want to know how to self-host than expected, and many users want to integrate Monito with a popular alerting tool to know when it detects important errors. So, you need to document these two guides and any supporting material around them for your next priorities. The product team also tells you that they’re shipping a new feature soon that allows users to define custom data structures to send to Monito, and that also needs documenting and adding to the quick start.

Thus, the process is ongoing. You slowly fill in missing documentation gaps based on user requirements, product requirements, and feedback.

Don’t forget the end users and the end-end users

I have spent most of my career working on documentation for developer tools. So, this book’s focus is more geared toward tools others use to build products for end users. This means there’s an extra level of interpretation above the documentation I create that the reader interprets into another application or code base that might even have its own documentation. I like to call these users “end-end users.” While it’s difficult to guess what that end-end use case might be, if you can find out via support channels, it can help you narrow down use cases and user journeys when you want some semblance of focus.

Take the Monito example. Currently, the documentation covers general use cases for those incorporating the tool into their own tools. Through user research, you find that Monito has a large user base in the finance sector. This gives you a slightly clearer idea about examples you can use in code snippets and explanations.

This chapter covered some fundamental building blocks of technical writing and creating documentation. It looked at why technical writing and documentation are important and what stakeholders often look for and expect with documentation.

You learned how to identify intended users reading documentation and what they want to understand and accomplish.

Finally, this chapter aimed to inspire you to keep at it when dealing with and balancing all the different stakeholders, users, and their needs.

The next chapter looks at the different types of documentation you might need to create and the purpose of each type.