TE
科技回声
首页24小时热榜最新最佳问答展示工作
GitHubTwitter
首页

科技回声

基于 Next.js 构建的科技新闻平台,提供全球科技新闻和讨论内容。

GitHubTwitter

首页

首页最新最佳问答展示工作

资源链接

HackerNews API原版 HackerNewsNext.js

© 2025 科技回声. 版权所有。

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

2 点作者 sky222428 天前
I&#x27;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, &quot;Oh yeah we have a documentation page for this, it&#x27;s buried here.&quot;<p>Or a different, but similar scenario: I&#x27;ll begin trying to solve a problem. I&#x27;ll search the team&#x27;s documentation and find nothing, but then I&#x27;ll be pointed to documentation that is exactly what I was looking for. <i>Ugh</i>.<p>So it&#x27;s kind of funny, I&#x27;ll be on a team with a wealth of information documenting everything, but it&#x27;s borderline useless since I can&#x27;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&#x27;s easy to navigate and easy to stumble upon what you need. I can&#x27;t be the only one that&#x27;s had this issue, right?<p>I guess at a higher level I&#x27;m realizing that this question really is, &quot;What&#x27;s the best way to structure documentation&quot;?<p>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.

2 条评论

theamk28 天前
One way to look at the problem is to try to determine _why_ is that you can&#x27;t find the documentation. I assume you used your wiki&#x27;s search function - then why couldn&#x27;t you find it?<p>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.<p>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 &quot;Keywords:&quot; section, including any error messages in full and adding a paragraph of motivation can help the documents to be found.<p>Are there too many matches, so you get overwhelmed and miss the correct page? In this case you&#x27;d want to work on titles, or go the other way and clean up the pages. Some basic category organization will be helpful too.<p>Sometimes the search is just bad. No excludes, or words don&#x27;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.<p>In the worst case, you&#x27;ll may try to give up on &quot;search&quot; completely and try a strict hierarchical organization, like Yahoo web directories in 1995. This may work great for introductory topics, but I don&#x27;t think this will work for every single doc. There is a reason no one uses web directories anymore.
评论 #43678741 未加载
PaulHoule28 天前
See the taxonomy of documentation here<p><a href="https:&#x2F;&#x2F;docs.divio.com&#x2F;documentation-system&#x2F;" rel="nofollow">https:&#x2F;&#x2F;docs.divio.com&#x2F;documentation-system&#x2F;</a><p>as opposed to the conventional documentation of a taxonomy.