Where do docs live?

Alyssa Rock — Tech writer. OSS community manager. DocOps enthusiast.
Feb 22, 2022, updated Jun 19, 2024 9 min read

I gave this lightning talk at a Write the Docs Bay Area meetup. It wasn’t recorded, but I can share the slides and my notes for the presentation in blog form!

In my lightning talk, I’m going to answer the question where do docs live. When I pose that question, I’m not talking about information architecture or content strategy stuff like where can you put your docs so that users can find them. I’m talking about where documentation writers live within a business organization, such as where do docs fall on the org chart.

So first off, let’s talk about why the question of where docs live matters. Aside from the fact that it gets asked a lot in the Write the Docs Slack, this question matters because it affects how docs and the people who write them are perceived within the business.

This question matters

I would argue that where docs live in the org chart implies a kind of framework or metaphor for how docs function and what value they provide to the business. And that perception matters because it affects how many resources are allocated to the docs:

  • It affects personnel hiring.
  • It affects investment in docs tooling and technology.
  • It can even mean the difference between whether the existence of documentation can be justified or not.

Perhaps most importantly, where the docs live in the org chart can affect whether the docs are perceived by business managers as a profit center or a cost center. I borrowed this profit center/cost center idea from the book Managing Writers by Richard Hamilton, which was one of the recent Write the Docs book club selections.

Richard Hamilton writes:

Profit center or cost center

Hamilton defines a profit center as a part of the business that generates more revenue than it spends. For example, product development is usually perceived this way.

By contrast, a cost center is perceived as a necessary service but one which doesn’t generate revenue. For example, IT, human resources, and janitorial services are typically thought of in this way.

It’s worth mentioning that there is no wrong place for docs to live. There’s pros and cons to each and you can bloom where you’re planted.

So, let’s dig in and talk about different places where docs could live in the org chart and how that metaphor affects the way docs are perceived, especially whether they are perceived as a cost center or profit center.

Each has its pros and cons

Development Development

If your docs live in development part of the org chart, the implied metaphor is that docs are part of the development process. In this model, developers are responsible for docs with writer support.

If you are working in a docs-as-code environment, development is probably the best place for documentation to live since writers are more likely to be embedded members of the development team.

Pros
  • Docs are part of profit center.
  • Plus, you get all the benefits that come from docs-as-code.
Cons
  • The only disadvantage I can think of from putting docs here comes in the situation where developers happen to have a culture where they don't really value the docs. If that important cultural piece isn't there, it can cause problems. (I'm speaking from a little bit of past experience here.)

Support Support

If documentation is housed with support in the business, the implied metaphor is that docs are a self-support tool. Their goal is to prevent or react to customer issues or problems with the product.

Usually, docs that live here are measured by how well they reduce the support call volume.

Pros
  • You can get really excellent feedback about where the customer pain points are with the product and use that data to make better docs.
Cons
  • That makes you a cost center.
  • Docs are sometimes an after-thought or the docs can sometimes be more reactionary than proactive.

IT or QA IT or QA

If documentation is put together with IT or QA in the org chart, the implied metaphor is that doc teams provide a service to engineering to offload some of their work. Docs are typically composed during the testing phase.

Pros
  • Docs have a lot of tooling needs and it can make sense to group them with the tool builders (IT). Getting tooling support can help solve some friction with creating docs.
Cons
  • Cost center, not a profit center.
  • In this model, docs are sometimes treated as second-class citizens and risk being siloed from development.
  • Also, if docs are being written this far along in the process, that's not very agile and it's less than ideal. It also makes it so that the writer can't be an advocate for the user earlier in the development process.
  • The good news is that the DevOps movement is working to change the business perception of IT as a cost center, but is anyone doing that for docs?

Product Product

When docs are put with product in the org chart, the implied metaphor is that docs are an integral part of the user’s experience with the product.

This is where I’m going to tip my hand and say the best case scenario is when documentation is under product. But even if your doc center doesn’t happen to live in product, that’s okay. You can still treat the docs as part of the product and evangelize them that way to upper management.

There are many advantages to having docs live in product:

  • Good docs improve sales. There’s a growing body of evidence that demonstrates that customers often use documentation to make a judgment about the quality of the product when they are in the evaluation stage of the sales process. They use the docs to evaluate how user-friendly the product is and whether it would be quick or costly to onboard their team with the tool. These factors can affect their decision to buy.
  • The documentation is part of the customer’s experience with the product. There’s no such thing as a perfect product with a perfect user interface that 100% perfectly self-explanatory. You need docs because products can’t stand 100% on their own. Like it or not, it’s part of the customer’s overall experience with the product. You can’t draw a bright white line between where the product ends and the docs begin. There’s a lot of overlap.
  • Technical writers benefit from being in the same part of the organization as UX. If your product is lucky enough to have UX designers, they should be among your tech writer’s best friends because UX enables them to work in a more agile way. UX designers can provide technical writers with helpful information about customer research so that they know who they are writing for and the specific use cases that product changes are meant to provide. UX can also provide early insights into product changes so that writers can begin planning documentation changes earlier in the development cycle. And writers have something to offer UX in return: they can act as reviewers on early mockups in order to provide usability feedback and to act as the user’s advocate in a way that devs sometimes can’t.
  • Documentation is improved by applying product management strategies. When docs are treated as a product, magical things happen. (Some of the best documentation out there is produced by teams that have full product development teams for their docs, such as Stripe.) But even if your docs don’t have a full product development team supporting them, your docs can still benefit from treating them like a product.

Docs live best in product

Let me give just one example of the benefits of applying product management strategies to documentation: creating a docs product roadmap!

Example of product management applied to docs: docs product roadmap

I work for Salt, which is a major open source project. I am their sole technical writer and they use a docs-as-code approach.

Over the past four months, I’ve been building out the Salt docs roadmap for our project because there’s just a lot of major, high-level documentation work that needs be done and not enough time to do it. So I needed a way to help people catch a vision of what improvements I could work, then help me prioritize them. I also needed to way to make my work visible and communicate what I was working on to the community.

I built this roadmap gradually over 3 months by embarking in a grand listening tour with both internal stakeholders and customers about what they would like to see done in the docs.

Whenever I have a conversation or see Slack message about something a coworker or stakeholder or customer says could be improved in the docs, I record that as a vote for these major initiatives.

Docs product roadmap home page

If you click on a card, I provide a lot of details about what the initiative really is about. I’ve based this on a template that I got from a previous product manager for articulating major feature requests:

  • Who-What-Wow (kind of like a user story)
  • Elevator pitch
  • Goals
  • Problems with the current process
  • Proposal for improved process
  • Caveats and additional considerations

Here’s an example:

Example docs product roadmap card

Docs product roadmaps have many advantages:

  • Roadmaps describe the long-term vision and strategy for the docs. I think that’s important because sometimes we can so caught up in documenting new features that we forget to zoom out and look at what kind of global improvements to the docs that will make our customers lives better. Having a roadmap primes you to think of the big picture more frequently.
  • Roadmaps provide a guide for implementing the strategy. Having a roadmap forces you to begin brainstorming a potential course of action for how you’d do the actual work.
  • Roadmaps encourage you to seek feedback from internal and external stakeholders. You can then use that feedback to prioritize work. For example, after I built out the cards on the roadmap, I then met with internal stakeholders and discussed which item they felt would be most important for me to work on. It was fascinating because they picked something that I didn’t think they would pick but it made total sense after that discussion.
  • Roadmaps create 2-way communication with customers. This helps makes the work I do visible and helps me communicate with my open source community. They can log in and make comments or vote for things directly and all of that is really helpful to me in setting my priorities. The roadmap also helps people see what work I’m doing and get a sense of the scale of the projects I’m taking on so it doesn’t just look like I’m off in my own world and not improving the docs.

Advantages of product roadmaps

Feel free to connect with me to ask more questions and hear more about how my docs product roadmap is working!

Docs live best in product