Documentation Defamation
“No one likes documentation”, chirped the little blue birds.
The bird quotes in the image above are all taken from real tweets and are listed below for accessibility:
- No one likes reading documentation. #DocsByDevs
- Protip: no one reads the documentation.
- Documentation: no one likes to write it. No one likes to read it.
- Wondering why no one likes to maintain documentation. I wonder if it’s really that painful?
- *No one* likes writing documentation. Liking that is the rarest skill of all. #NotReallyKidding
I can’t argue with “liking to write documentation” being a rare skill, since so many people are vocal about disliking it. That tweet might prove to be true, in which case, technical writers should simply be more appreciated for the rare gems that they are. In this blog post, however, I’m going to explain:
- How technical writing fits in across the organization and how good documentation helps everyone.
- Several things technical writers often do in addition to writing.
- Some of the key elements and benefits of good documentation.
1. Technical Writing Across the Organization
Many people aren’t familiar with the central role of technical writing in their organization. They don’t realize it isn’t just typing up sets of instructions and definitions—at least it doesn’t have to (and probably shouldn’t) be only that. Let’s look at some of the key areas that benefit from technical writing throughout the product release lifecycle.
Note: I’m focusing on technical writing in a software company because of my experience in that area. This might vary for technical writers in other industries.
Design and Development
Technical writers help ensure things are uniform between teams and products throughout the company. Many engineering departments use Agile development and have multiple scrum teams. Your technical writer (or technical writing team) is often deeply familiar with the work across multiple scrum teams. Technical writers can spot inconsistencies in terminology, design, and processes.
Writing out instructions for processes can highlight when a process is confusing, cumbersome, or likely to generate unnecessary contacts with the Support team. Having technical writers involved early in conversations and the development process will save time when it’s more cost effective to do so.
Testing
Giving your technical writer access to early builds of the release adds another layer of QA to the process. As technical writers go through the product to look at new screens and determine what needs to be documented and updated, they perform ad-hoc and integration testing that may closely resemble what a customer will do in the wild. This is especially true when setting up examples for documentation. In many ways, technical writers are some of the first customers to use your product.
Marketing
Documentation isn’t designed to be used for marketing, but it does market your product to prospective customers. It provides a credible source of technical information about what your products can do with the level of detail they’re looking for when researching solutions to solve their problems. The documentation also acts as a reliable information source for your actual marketing materials.
Google Analytics makes it easy to prove people are reading the docs and finding them in their searches. Technical writers sometimes become SEO wizards who balance using the right keywords for the search engines and following other SEO best practices, while keeping the flow of language natural for human readers. When you want people to read your docs (and technical writers really, really want that), then you ensure the docs are easy to find. This, of course, applies to the documentation platform search features and information architecture, in addition to external search engines.
Sales
Having good documentation creates a better trial experience. Easy-to-use docs with onboarding and detailed walkthroughs get people up and running without needing additional support. If you’ve already made your docs easy to find, then salespeople will also use them to find answers to questions from prospects without having to reach out to other teams for support and answers.
As Richard Douglas notes in his “How to Successfully Evaluate a Monitoring Tool” blog post, “you are not just evaluating the software,” and the quality of the technical documentation should be a consideration. Documentation is one of the ways prospects get an overall sense of the type of support they’ll receive going forward when making purchasing decisions.
Sales Engineering
Sales engineers are regularly asked to present demos on new products, new capabilities, or more obscure features. Their jobs can be made easier and their demos more successful by having complete documentation available to them when they need it. Quality documentation is empowering and supports people across the organization.
Product
Another outcome provided by documentation is product and feature adoption. When new features are released and are fully documented, customers can start using them with confidence. Documentation surfaces existing features longtime customers didn’t know existed or simply forgot about over time. It’s not uncommon for companies to release new features before the documentation is available—and then wonder why their support workload increases or feature adoption is lower than expected.
Support
Great documentation leads to support case deflection and helps your Support team find answers for customers. Useful documentation gets new Support team members up and running faster. Good communication from the Support team to the technical writing team highlights gaps in the documentation and creates a feedback loop for improving it.
Training
Documentation provides source material and supporting references for training courses and videos. Training and tutorial videos can then be embedded into applicable documentation articles to help people learn through different examples and media types.
2. Technical Writing Activities
Many of the people I know through the Write the Docs community have technical writing roles that encompass much more than writing documentation (to their delight or dismay, depending on the individual). They write code samples, design and build documentation websites, create complex diagrams, edit images and make animations, use source control tools, script tutorial videos, improve in-product messaging, agonize over terminology, and more. Some of them write documentation specifically for developers and require a strong programming background themselves.
In my own experience, I’m noticing more people finding me through LinkedIn by searching for “Technical Writer + Developer” keywords.
Technical writers work as product detectives, poring over organic communication (e.g., Slack channels, emails, forums, social), trying to find questions that were asked to learn if there’s a gap in the documentation, an area in need of improvement, or a piece of product information that wasn’t easily found. They interview subject matter experts (usually engineers, product managers, and sales engineers) and learn to ask the right questions. Many of them become subject matter experts themselves (if they weren’t already). They’re the product librarians who catalog and share information.
Writing and Communication Skills
For documentation to be helpful, it requires writing and teaching skills. Information must be organized and presented in a way that’s accessible. It takes significant skills to communicate complicated technical topics in clear language and break them into easy-to-understand bits, before then creating connections between other topics. Effort goes into presenting the information in a way that incorporates images, note boxes, lists, and other methods to intentionally break a wall of text into something more visually interesting and less intimidating. Some might confuse typing skills with communication skills when it comes to documentation, but actual writing skills are required. Excellent writing skills are sought by the majority of employers and poor writing skills are costing businesses billions of dollars.
I recently attended a presentation on a technical topic I was hoping to learn more about. It was clear the presenter was experienced and knowledgeable about the technology. However, I was having a difficult time learning from the session because the information lacked organization and flow. It wasn’t in a logical order (didn’t build upon topics) nor did it explain how the items were connected (which means I didn’t get the overall picture). It was as though random facts and definitions were being thrown at me as we jumped between topics without a meaningful transition.
This is often what happens when a subject matter expert writes documentation but doesn’t know or care how to explain things. Unfortunately, many organizations have their subject matter experts write the documentation when they don’t have a person or team dedicated to it. It’s usually apparent when the documentation was created by someone who was forced to write it.
Education Teams and Titles
In the world of technical writing, you’ll find various job titles (e.g., technical writer, information developer, documentation specialist, content developer). Some of the newer titles and teams I’ve seen include product educators and developer educators (depending on the intended audience). I believe these titles more accurately reflect what many technical writers do these days. The goal is to educate and provide a self-service method of support and learning to your community.
A Note About Accidental Technical Writing
In the SQL Server community, we often talk about the Accidental DBA—someone who might not have set out to be a DBA but is now in the role (officially or not, full time or as a secondary responsibility at work). These Accidental DBAs have a lot of on-the-job learning to do and often don’t know about best practices up front. In many ways, I have been an accidental technical writer throughout my career. No matter if my role was in support, development, testing, or research, I always ended up being the person to write about the programs, processes, troubleshooting, definitions, and more. Helping people understand my work or sharing something I learned has been a lifelong passion.
When SentryOne recognized the need to have a dedicated technical writer, I jumped at the opportunity to revamp the documentation and turn it into something more. My lack of formal technical writing training might have led me to tackle this project differently than some in the industry. I have thought of and managed SentryOne Docs as a product and service from the start. I wanted documentation that combined different sources of technical content and was perhaps a bit friendlier and less formal than classic technical writing. This eventually became the Product Education team, which included documentation and training.
3. Good Documentation
How do you know if your documentation is good? When people can do the following:
- Find it
- Use and share it
- Return to it
Once customers and employees realize the documentation is worth their time and is easy to use, they start to think of it as the first place to check for answers. It gains credibility, and this trust adds to the usage pattern. Your documentation should be treated like a living and breathing ecosystem of information that stays up to date as your product changes. If you don’t maintain it, its usefulness and reputation will decline.
Related Content
If you have related content (e.g., other documentation articles, blog posts, training courses, video tutorials, troubleshooting articles, code samples, third-party documentation), are they referenced in your documentation? Any materials that add examples and context to the content should be linked or embedded.
Solicit Feedback
Adding rating and comment widgets to your documentation will help you learn what’s succeeding or falling short. Technical writers are eager for meaningful and actionable feedback. If you think the documentation is bad, it’s fine to say so, but specifying why it’s bad (i.e., a step is missing, a definition is ambiguous, the image no longer matches the software) is a much better way to help improve the documentation. Positive reinforcement doesn’t hurt, either. If you show the helpful articles some love, then patterns around documentation features that are most effective will emerge. It also reminds the content creators that people do read (and appreciate) the docs.
Actually, People Do Read Documentation
Effective technical writing takes skills that often go unnoticed by those on the outside of the process. It’s important to have a team dedicated to documentation and product education to produce materials your customers and teammates will want to use. No matter how many little birds say they don’t read the documentation, plenty of people do read the docs, and within your organization, many of them depend on the docs to be successful in their roles.
If you aren’t investing time and resources into this area of your business, you probably have many teams suffering and struggling because of it. Well-written documentation can pay for itself many times over through reduced support calls, increased productivity and success for teams across your organization, and passive marketing.
There’s an old saying about horses and water that I often think about when I see people avoiding the documentation. You can have great documentation readily available, but some little birds are always going to avoid it as long as possible.
Bird #1: Was able to complete the task after much trial and error. Once again, just read documentation please.
Bird #2: Spent 12 hours working on a problem before spending just 5 minutes to read the docs and actually resolve it.
