Most companies don’t have a problem with too little documentation. Instead, the documentation is hard to find when needed.
I’m a documentarian and this is one of my favorite topics. My go to is creating a wiki for the team. The wiki is organized into hubs. There is a hub for each team. There is a hub for each topic such as security, new employee onboarding, etc. There might be a hub for each bigger project.
A hub contains information about people, systems, and processes. For example, there might be a section for external services. Each of those gets a hub too.
Everything is hyperlinked. Search sucks in most wiki-like tools. Hierarchies are inadequate to capture the complexities of reality. Each page or hub is often relevant in multiple places and should be linked. Links should also be included to external resources whenever they will save time. This can include linking to concrete Slack conversations, Jira tickets, and pull requests.
During onboarding each new team member is asked to improve the onboarding documentation. Anyone can change any documentation. It’s not possible to keep documentation relevant if each team member does not use it.
I like to use the strangler fig pattern. This concept is used to build a new version of a system alongside an existing legacy system, but I think the idea also works for building a new documentation system alongside a heap of old unorganized info.
Start by building a structure with some empty templates, a d a few instructional examples. Then ask the team to bring over information into the new system whenever they find something useful in the old system. Minimally, ask them to drop a link in a relevant hub or two. Even better if they spend 5 minutes copying it over to the new system, and adding a note with a link to the new version in the old system.
Over time the new documentation system will strangle the old one. Hence the name.
Team participation is a must. This will not work if it is a one man effort. Have managers push and encourage people to participate in the documentation effort.
Side note: the strangler gig is a fazcinating plant.
I’m a documentarian and this is one of my favorite topics. My go to is creating a wiki for the team. The wiki is organized into hubs. There is a hub for each team. There is a hub for each topic such as security, new employee onboarding, etc. There might be a hub for each bigger project.
A hub contains information about people, systems, and processes. For example, there might be a section for external services. Each of those gets a hub too.
Everything is hyperlinked. Search sucks in most wiki-like tools. Hierarchies are inadequate to capture the complexities of reality. Each page or hub is often relevant in multiple places and should be linked. Links should also be included to external resources whenever they will save time. This can include linking to concrete Slack conversations, Jira tickets, and pull requests.
During onboarding each new team member is asked to improve the onboarding documentation. Anyone can change any documentation. It’s not possible to keep documentation relevant if each team member does not use it.
Here is an article that I wrote about this a while back https://koliber.com/articles/engineering-documentation-best-...
I am really passionate about this and help companies do documentation well in engineering teams.