Here are things that I do to improve the documentation situation. They are not perfect, and the results are not immediate. Over time though, I notice how they contribute to a more useful set of documentation.
- hyperlink, hyperlink, hyperlink. Anything relevant should be linked from at least one, and preferably multiple relevant places. That Tim Berners-Lee guy was on to something. More on this later.
- many tools use a hierarchy (e.g. folders) as the primary way of organizing information. People have spent countless hours arguing about the correct organization of this hierarchy, or the best location for a document. Don't do that -- it's a waste of time and you'll never get it right. While hierarchies are often useful, it is not as important where in a hierarchy a document lives. Hyperlinks allow you to link documents that relate in various ways, creating a graph of knowledge. The hierarchy is just one of the ways those links can fall.
- don't fret the tool. Information can live in Confluence, Notion, a wiki, Google sheets, presentations, GitHub READMEs, public Slack channels, recorded Loom videos, and the list goes on. Hyperlink relevant things together. If you have a postmortem document, link to slack conversation. If you have a document describing a performance improvement, add links to relevant git changes, or recorded demos. Use the best tool for the job, and hyperlink things. Prefer tools that allow hyperlink addressing.
- hub documents rule. Each team has a hub. Each project has a hub. Each process has a hub. Each department has a hub. A hub is an index, a homepage, and a starting point. If someone is looking for something, they can follow the hubs. If you want to find out what the metrics on project XYZ are, remember that team Houston did the project, go to their hub, go to their project list, find XYZ, and hopefully you'll get your answer.
- encourage a culture of common ownership of all documentation from the start. All documentation goes out of date and no single person can keep it up to date. In the onboarding, I tell each team member to modify the onboarding documentation any time they hit a snag, have an unanswered question, or see something that is unclear or wrong. Doing this on day one gives explicit permission to edit documentation. With modern tools, there is an edit history so there should be no fear of losing things. It seems that people consider creating and updating documentation someone else's job. And not in a bad way, but rather in a "I'm not allowed to do it" way.
- someone else said this, but if you are answering a question on Slack, email, or a PR review, spend a bit more time writing a clear response, and then add it to your wiki. Then, write a quick summary and include a link to the newly-written document. Do this a lot, but use a positive tone.
- if someone asks a question and the answer already exists, direct them to the documentation. Important: don't be a jerk about it. Furthermore, I often don't link directly to the document, but link to a hub document where that info is stored and tell the person where to find the exact link. This will require an extra click from the person, but it shows them the context of where the information exists. This improves the chances they can find something on their own later.
- simplify and clarify key documentation. Brevity and clarity are key to consumption. It's a skill. Do this iteratively.
- loudly and publicly celebrate people who make meaningful documentation contributions.
- when someone shares that they are leaving, make documenting their primary job for the remainder of their stay. If you tell them to finish their work, they may be successful or not. In either way, someone else will need to either finish the work, or maintain it. If you tell them focus on documenting, this will enable others to finish or support the work better. It's more leveraged.
- when someone goes on vacation, ask them to document some part of their work so that people don't call them on vacation. It's a good motivator to not to be called on vacation.
- hyperlink. Search and navigation are the primary ways of discovering knowledge. Search is limited to a single platform or system, and does not always work well. Hyperlinking allow you to associate information in time, space, relationship, which allows you to use common sense and navigate the knowledge graph.