1. I'd Rather Be Writing
2. Docs
3. Chapter 14: Documentation processes and methodology

Changing internal doc culture

Download PDF

One of the most influential aspects that will determine your experience as a technical writer at a company is the company’s documentation culture and environment. If you find yourself in an organization with a poor documentation culture, it can be difficult if not impossible to change it. A poor documentation culture/environment leads to a high turnover on doc teams, loss of motivation for existing writers (especially as their colleagues constantly leave, which increases the workload), and contributes to a downward spiral of tasks you can never quite get a handle on. In this topic, I outline six strategies you can implement to influence change in your company’s documentation culture, bringing about a more positive and healthy environment.

• Characteristics of a poor documentation environment
• Six ways to change documentation culture
  • 1. Attend engineering Scrum/Kanban meetings with engineers
  • 2. Become visible by letting people know what you’ve written or updated
  • 3. Relay customer insights back to product teams
  • 4. Move the needle in a noticeable way with doc quality
  • 5. Be in the right group organizationally
  • 6. Apply your energy to the right projects
• Conclusion

Characteristics of a poor documentation environment

Poor documentation environments can be characterized by the following:

• Lack of executive sponsorship or support. In these companies, no one at the executive level is a strong believer in docs. They might give lip service to the importance of docs but then fail to adequately staff resources, not only resources for writers but also for the tools infrastructure and any supporting engineers. Docs rarely bubble up to their radar, and tech writers are invisible to them. These leaders give the impression that they don’t care about docs, and the attitude tends to flow downward through leadership chains.

• Lack of integration in formal processes. Engineering processes that don’t require documentation as part of the “definition of done,” or which don’t include documentation as any requirement for product development and release, can also devalue the tech writer role. Documentation requests might come in at the last minute, when the features are fully coded and ready for release in a few days. In these companies, there’s no formal way documentation is integrated into development and release processes. It’s all ad hoc and last minute.

• Lack of enough resources for the required work. In a company with poor documentation culture, you might always feel short-handed and unable to ramp up on the needed work. You might move from project to project in a cursory way, never able to adequately learn the technology or become a SME before you have to start on the next project, which might be a completely different technical realm. The lack of resources goes hand in hand with high turnover rates. As soon as someone arrives, another leaves, and you end up doing more work than your role alone, which also motivates more turnover because people are overworked.

• Check-box mentality is common. If product and department leaders see documentation as simply a box to check box to select and nothing more, this can also trivialize your experience at that company, especially if that check box has no standards or minimum bar associated with it. This “check-box mentality” can be characteristic of people who show little interest in the actual user experience. As soon as the docs are done, they’re crossed off the list and rarely revisited.

• Support for tooling is underfunded for the requirements. You might need robust tools to provide the kind of experience people require (PDF, localization, gated docs, etc.), but the company might not want to fund any tooling resources, insisting that you use open-source tools instead, or not providing enough time to build out tooling you need.

Most tech writers are familiar with some of these aspects. I’ve written about these topics multiple times on my blog, especially in these two series:

• Reflecting seven years later about why we were laid off
• Value arguments for docs and tech comm

In the following sections, I’ll explore processes you can implement to change your documentation culture.

One question is whether a company’s documentation culture can actually be changed through efforts from the tech comm group. I believe change is possible, to an extent. You might not convert your CEO into a doc champion, but you can influence your environment and culture if you work hard at doing so. Especially if your company has a business reason that heavily depends on the customer experience, you have a shot at influencing upward. These efforts should be factored into your team’s regular processes and goals.

Among all processes described in this section, changing culture is the most difficult because it requires changing the attitudes and minds of others for which you have little control. It also requires a lot of marketing work that you might not have the bandwidth for. I also can’t say that I’ve had a ton of success in this area, but I will share the strategies that have worked for me.

Six ways to change documentation culture

The following are six ways to change documentation culture at a company.

1. Attend engineering Scrum/Kanban meetings with engineers

My best experiences have been when I’m integrated closely with engineering teams, attending their daily standups, sprint demos, and other scrum/kanban meetings. Organizational setups don’t always allow for this type of embedded engineering-team integration, but hands-down, whenever I’ve done this, it has absolutely changed my experience with the product team in extremely positive ways. Integrating with engineering teams builds relationships with these groups, and they see your value, and you can anticipate their doc needs.

The constant problem is that tech writers usually support multiple teams, so integrating fully would drain the tech writer’s time too much. It doesn’t really work to attend regular standups for more than a couple of engineering teams, but consider maybe attending 1-2 standups a day, rotating to different engineering teams depending on how many teams you support. Even if you just drop in once a week to a different team each day, this will dramatically change your visibility and rapport with the teams. Usually, teams don’t have so much doc work that they need you there daily (and if you do attend the same team’s standup on a daily basis, you might actually feel it’s a waste of time), so occasional attendance might be ideal and build the needed rapport just fine.

2. Become visible by letting people know what you’ve written or updated

A critical step to influencing change is to make your influence visible. As one of the most visible tech comm bloggers in this space, I know how to make myself known to those around me. The recipe for visibility on the web is simple: write relevant content and share it with those around you — over and over and over.

In the context of documentation teams, you don’t need to write blog posts. Instead, make a list of all your recent updates each month, and then send it out to as many relevant stakeholders as you can. This will help them see on a regular basis what your team is creating. They’ll come to understand your role, what kind of content you create, and what’s being changed. When the topic of documentation comes up, you’ll be first on their mind.

3. Relay customer insights back to product teams

One of the most valuable assets at a company is customer knowledge. If you can communicate customer insights to internal product teams, this raises your value and relevance in a major way. Add a feedback form at the bottom of each of your doc pages. On a monthly basis, review all the feedback, analyze it, and send it out to product teams and other stakeholders. Include other metrics about the most popular pages and trending search results. People love this kind of customer insight, especially business leaders trying to understand market trends.

If you want to take it a step further, undertake a competitive analysis highlighting how the developer’s experience on your company’s products compares with the developer experience on competitor products.

4. Move the needle in a noticeable way with doc quality

Doc champions are converted to a pro-docs mentality through close experiences with documentation. I remember hearing a developer petition and advocate for product teams to have technical writers work on a specific product’s documentation because of the way we turned around documentation for another product. If you can turn docs around in impressive ways, translating engineering-speak into real English, making the steps easy to follow and concrete, people will notice. You can’t just fix grammar and punctuation — you have to actually move the quality needle in noticeable ways. For example, implement a workflow map to visualize a complex process.

When you do improve docs in significant ways, others will start to ask for tech writers to play closer roles in creating the documentation, not just editing and publishing docs that product teams write. If you insist on high standards in docs, such as requiring teams to provide a sample app, testing out all the steps yourself and ensuring they work, adding troubleshooting topics, glossaries, search, etc., people will sense the value you’re providing and start to champion the inclusion of docs as a requirement for each product release. I’ve had many experiences where product teams wrote some documentation, floated it to developer advocates, and the developer advocates told the product team to send it to the doc group to “polish.” But by polish, they really meant fix the organization, structure, clarity, readability, and more. These developer advocates had learned what we could do with content and started insisting on it as a standard.

5. Be in the right group organizationally

Okay, this last point is controversial and opinionated, but it can’t be left out. Where you are in the organization matters. Are you grouped in Product, Marketing, Engineering, Support, or some other department? I’ve been in nearly every organizational discipline, and my best experiences are when I’m in Engineering. This is because engineers are heavily involved in the product development phase, and this is where you want to be as a technical writer. Marketers are too involved in the release phase, support in the post-release phase, and product in the pre-development phase. But engineers are in the development phase. As a technical writer, you’re developing content, and you need the sprint cadence of weekly development and workflows. Engineering understands this flow, and documentation groups fit well into it. (Many of these other groups don’t even follow Scrum/Kanban workflows.)

If you’re not in the right group now, don’t worry. In my 5 years at Amazon, I had 5 different managers and experienced about the same number of re-orgs. I’m sure I could have influenced where the doc group was moved during different re-org periods, but I rarely had any foreknowledge of upcoming re-orgs; they just happened without warning.

6. Apply your energy to the right projects

Most organizations have key strategies or goals they’re focusing on. For example, your organization might have a goal to get 30 partners to integrate a particular technology. If you align your documentation efforts in this same technology direction, helping fulfill the executive’s key objective, it will raise your importance to the executive leaders in the organization and make documentation a more important function. I wrote about this in more detail in 2. Assess the identified work against strategic priorities in “Processes for managing large documentation projects.” In short, don’t assume all documentation is equal. It isn’t. If you spend a lot of time and effort on docs that no one uses or cares about, you’ll have misused your energy.

Conclusion

Company culture towards documentation isn’t easy to change, and just like people don’t change overnight, company culture doesn’t transform overnight either. Many perceptions people have around documentation have been hardened by years of disappointment or frustration with documentation. You might be facing an uphill battle that began when the previous tech writers in your role failed to deliver anything of substantial value, or you might be battling against people who believe no one reads docs and so docs are a formality only, not actually something that is used. Changing people’s minds about the importance of documentation might be a gradual process that you influence over several years. But if you follow the six strategies I outlined here (in greater degrees if you want faster change), you will eventually have success.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.