What can documentarians accomplish?

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.