Building documentation mindshare in a company¶
Having a culture of documentation inside of a company is a great thing. Building a culture around documentation however is a hard thing to do. This will be a guide with some information and suggestions for how to go about bringing good docs into a company.
State the problem¶
There are a lot of nebulous problems in communication inside of organizations. You want to start small with something that you can nail. When I’ve done this in the past, it looks something like this:
We will solve the issue of documentation around internal project documentation in our Engineering organization.
Which brings me to the next point.
Start in engineering¶
Starting in the engineering organization I think is the simplest way to affect change on documentation culture. There are lots of other parts of an organization, but it’s easier to get permission to work on just the internal stuff to engineering. Think things like:
- Project documentation
- Operations documentation
- Playbooks
- Monitoring Information
- Best Practices
- Style Guides
Gather input¶
You will want members from all of the teams in your organization to be invited to the planning meetings. They don’t need to come, but you need to make sure it’s an open and public discussion. This validates the outcome of the planning, and makes sure that you are taking into account all of the use cases of your team.
Build a taxonomy¶
A big problem with a lot of documentation systems is that they have been organized organically, AKA have no organization. If you build out a structure for people to start, and keep it consistent across projects, it will make everyones lives easier.
Note
You need to have an answer to the “Where do I put it?” question.
Make it easy¶
Getting started should be as easy and straight-forward as possible. Most people don’t like change, and introducing new tooling and things will already rouse a negative response in some. This is why you need to make it as simple as possible to get started.
Build templates¶
It should take about 5 seconds to get a basic outline of the documentation for a project started.
Also have a standard hierarchy for the docs, so that people know where to look for things in any project.
Have regular meetings throughout the process¶
Having a weekly standing meeting where you keep track of the progress along all the stages is important. This gives people a known place to go and discuss issues or ideas. It also provides a sense that the project is moving forward. At the beginning these meetings will be used to plan and track implementation. After implementation, it will be a place to drive adoption and gather feedback.
Make it long-term¶
Something like a good documentation system also needs pretty constant care and feeding, reorganizing, and other maintained work. If you view this project as getting the tools in place, without a long term commitment, it will fail just like your last system.
