Ask HN: How do you prevent documentation from becoming tribal knowledge? | Hacker News Reader

Ask HN: How do you prevent documentation from becoming tribal knowledge?

2 pointssky22243 comments

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.

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.

> Sometimes the search is just bad...

Honestly, I think this is the biggest issue with my company's current system. Confluence search just doesn't seem to... well, search (I'm also not the only person to have this issue where I work). What I mean is that I'll search for a page that I know exists, but Confluence just won't include it, so it seems like Atlassian's search functionality is behaving poorly.

This actually might be something I should bring up with my department to see if there's possibly a fix.

I like the suggestion of adding a keywords section, that actually might help a lot as well. Inclusion of an AI agent would probably be beneficial as well, although may be a little bit harder to get implemented since my company is being very cautious about what data we feed into models for privacy, legal, etc reasons.

See the taxonomy of documentation here

https://docs.divio.com/documentation-system/

as opposed to the conventional documentation of a taxonomy.

Reply on news.ycombinator.com