How do you prevent documentation from becoming tribal knowledge?

Question

I've run into this situation before where I join a team and person X begins helping me with something, then person Y comes along and says, "Oh yeah we have a documentation page for this, it's buried here."Or a different, but similar scenario: I'll begin trying to solve a problem. I'll search the team's documentation and find nothing, but then I'll be pointed to documentation that is exactly what I was looking for. Ugh.So it's kind of funny, I'll be on a team with a wealth of information documenting everything, but it's borderline useless since I can't find what I need when I need it, and only Joe who has been here for 15 years knows exactly how everything is laid out and knows where to point me. How do I prevent this? How can I structure my documentation so it's easy to navigate and easy to stumble upon what you need. I can't be the only one that's had this issue, right?I guess at a higher level I'm realizing that this question really is, "What's the best way to structure documentation"?Additionally, any tips on how to do this in Confluence? I feel like at least 20% of the problem is due to how awful it is to create anything remotely navigable in that tool.

theamk · Accepted Answer

One way to look at the problem is to try to determine _why_ is that you can't find the documentation. I assume you used your wiki's search function - then why couldn't you find it?
Are you not familiar with keywords, so your search results return nothing? In this case, a glossary or a list of (company-specific) synonyms might help.
A common cause of empty search results is if the pages are so short that you need exact keywords to bring them up. In this case, adding explicit "Keywords:" section, including any error messages in full and adding a paragraph of motivation can help the documents to be found.
Are there too many matches, so you get overwhelmed and miss the correct page? In this case you'd want to work on titles, or go the other way and clean up the pages. Some basic category organization will be helpful too.
Sometimes the search is just bad. No excludes, or words don't match half of the time, or random matches, or knowledge is spread across half-a-dozen websites... This is hard to fix, but bringing up a separate search system (or AI agent nowadays) might still be easier than rewriting every single page to accommodate broken search.
In the worst case, you'll may try to give up on "search" completely and try a strict hierarchical organization, like Yahoo web directories in 1995. This may work great for introductory topics, but I don't think this will work for every single doc. There is a reason no one uses web directories anymore.

PaulHoule · Answer

See the taxonomy of documentation herehttps://docs.divio.com/documentation-system/as opposed to the conventional documentation of a taxonomy.