Ask HN: How do you manage your companies knowledge base?

[hifikuno]

After losing a few key personnel lately I have become painfully aware of the amount of knowledge stuck with individuals. While we do have a wiki of knowledge, a lot of the pages are outdated, incorrect or just not needed anymore.

My problem is, I know that we are missing information, what I don't know is how to tease out that information from myself and other coworkers. Do you have any advice on how to get the knowledge out of my coworkers and into the knowledge base? Or, do you have a book you recommend? I have found a few books on knowledge bases but the reviews seem to be pretty hit and miss.

Edit: After talking with some friends about it I think I was able to articulate my main issue I have. In making this documentation it feels like I am winging it. However, all my training has been in coding and coding always has standards, guidelines and frameworks. It's hard for me to just work on the docs as I feel like I should be following some sort of standard as I do it.

Edit: Currently I am stuck with Confluence as the actual technology to use.

[bluGill]

I have a strict rule, anytime someone asks me a question I respond by checking the documentation for that, and writing or fixing it as needed. Once I think the documentation is correct I tell them how to find it, and ask them to tell me where something doesn't make sense so I can fix it.

As an expert I often think things are obvious that are not. So it takes a few rounds to make useful documentation.

[ethbr0]

I call this read-through documentation (a la caching), in that you're always reading from the documentation (cache) and a missing document pulls it into the documentation (by writing it), before servicing the request.

It takes discipline, as otherwise everyone skips the "write documentation" step, and it will annoy some people with high priority issues.

But IMHO, it's the only thing that actually scales if you truly want comprehensive, continuously-updated documentation.

Side note: An excellent way to generate drafts for missing content is have your new hires write them as they get up to speed. By definition they're looking everything up, so they'll notice gaps. And they have time, before they're fully up to speed. And as long as someone with knowledge proofs their draft, their lack of experience shouldn't matter.

[cmonnow]

My strict rule : Never write/store documentation that is separate from underlying 0s & 1s. It always goes out of sync.

We are currently in the process of creating a data dictionary for our company.

I put down a rule that we are not ever going to create a SEPARATE WordDoc/Wiki/Evernote/GenZ-tool.

If it is code, document its meaning (english explanation for laymen) in the doc string. If it is data, document its meaning in the column's metadata (all database systems provide a property/comment/description capability at table & column level). If it requires complex diagrams, put these in whatever files (doc/image/pdf/mp3), store it as a blob in a database and create a link it in original code comments/column metadata.

All this data is then constantly pulled into some data-mart on top of which a query-able UI is created.

Every documentation must be literally "Tied" to actual systems making money for the company.

If a new code/data is created or updated, and it's missing documentation, PR is not approved. Once the basic technical setup of tying code/data with comments/metadata is done, enforcing this rule of updating documentation is the job of management/CTO culture.

[a_bonobo]

This is a great approach.

How do you deal with outdated info that's still useful to keep around?

I have a few internal wiki-pages which are 80% 'stuff I tried that doesn't work but I'd like to keep around because the tries are valuable in case I re-visit these angles', 20% 'stuff that worked in the end'. I find the 80% confuse newcomers, and I still have to explain which parts are important.

[arrozcomfeijao]

We do the exact same thing. Whenever we answer a question, the MO is to "point to the answer in the documentation and, if it's not there, add it and then point to it".

[kaycebasques]

I used this approach when doing the DevRel for Chrome DevTools. I would browse Stack Overflow for uses cases not explained in the docs, add a doc for it, and then link my Stack Overflow answer to the (newly created) official doc.

[Semaphor]

That is a great idea. We have a company-wide OneNote notebook with some (extremely) rudimentary documentation, I hope I’ll remember this the next time someone asks me a question, so I can add it there :)

[100011_100001]

Where is the documentation stored? One of my main blocks is how hard it is to update documentation.

[phphphphp]

I've not tried this at scale so it remains theory for me, but at a previous company, I proposed that we tackle this problem in the same way medical literature is managed by health organisations. That is, every page is owned and every page has an expiry: when a page expires, the owners are obligated to review it. The "yikes" part of that idea is that it feels burdensome, but that's because retaining and managing knowledge is burdensome and businesses should be measuring knowledge as an asset (or liability) and budgeting accordingly.

Ultimately, most people are digital maximalists when they'd be better off being digital minimalists. I (in my personal life and in the small teams I work with) purposefully delete things that I do not wish to accept the burden of owning. Either something is important enough to justify the burden of ensuring it's accurate, or it isn't and it is deleted.

I have found that thinking about documentation in these terms, it becomes clear what to document and what not to document, and it forces better practices elsewhere in the business -- like writing code that clearly communicates the why, or designing business processes that leverage a core set of business information.

[kaycebasques]

As a technical writer of 9+ years I can share some concrete experience related to your theory. The theory is right on the money. Assigning an owner and tracking last review date is a very effective practice. Google had a great system (go/fresh-source) in their internal doc infrastructure, g3doc. I learned recently that parts of Microsoft have a similar setup. You put an "owner" field in the YAML frontmatter of your doc (the value is the username of the person who owns the doc), as well as a "last review" field (value is last review date). Then you build a reporting system that tracks who is keeping their docs up-to-date and who is not. You can ensure that people don't game it (e.g. just updating the "last review" field without actually looking at the docs) by cross-referencing with other metrics, such as number of bugs opened that are related to that area of the docs.

[WJW]

I think that expiry of documentation is a great idea, but it could go further:

- Often, teams "own" stuff but the real knowledge is stuck inside individuals. This type of thing would need to survive the relentless reorg cycle that seems ubiquitous in tech companies.

- The health sector seems to have longer overall tenures than the tech sector. At the very least this kind of system should somehow link into the HR administration, so that if a document owner leaves there can be an alert "This document is now unowned!". Of course, that alert also needs someone to monitor that.

- What would you use as a metric for the asset-ness of knowledge? Some types of knowledge seem more important than others, but it is not clear to me how to quantify that.

Your point about digital minimalism is very good though. A lot of things that should be deleted are instead kept around in a form of digital hoarding behavior.

[leftnode]

There's a piece of software (that I have no affiliation with) that has a feature like this built in named Guru: https://www.getguru.com

[hifikuno]

Oh my god, the expiry date is an amazing idea. So much of our data is never updated, and forcing the creator to update it or delete it before the expiry date would clear up so much old and outdated information.

[kaycebasques]

> After losing a few key personnel lately I have become painfully aware of the amount of knowledge stuck with individuals

Speaking as a technical writer who has worked deeply with engineering teams. You might be "missing the forest for the trees" here a bit by focusing on documentation technology rather than engineering culture. Your team doesn't feel compelled or rewarded to create documentation. Go to your head of engineering, CEO, etc., share the story of losing critical company knowledge when these people left, and suggest to them that the team needs to be properly incentivized to create docs. Make documentation a factor in promotion, bonuses, social recognition, etc.

The technology is more likely to take care of itself after that. Rather, you'll have more engagement from stakeholders and will have more confidence around what will work.

But beyond that, in terms of wrapping your head around information architecture, Divio's documentation system is a great start: https://documentation.divio.com/

You can hire or find technical writers to give brown bag lunches on documentation basics. I would do it for you. Poke around on my HN profile and you'll find how to contact me.

Last, I would set the expectation that it's OK to feel like you're winging the documentation. I suspect a lot of engineers don't write docs because they feel they are bad writers and don't know what they're doing. Just focus on creating a safe space to creating docs and keeping them up-to-date first. Over time as you all use each other's docs you will figure out why they suck.

The Write The Docs conference videos on YouTube are also an excellent resource.

[kaycebasques]

What I mentioned in the parent comment is the top-down part of the strategy. The other side is the bottom-up leadership by example as mentioned elsewhere in this thread. Someone asks you for help, you point them to a doc and ask if they still have questions (and update the doc if they unsurface any gaps). If the doc doesn't exist you quickly create it and iterate.

[billbrown]

Quick link - https://www.youtube.com/c/WritetheDocs/playlists

[maccard]

We use notion (https://www.notion.so/) but the tool itself doesn't really matter. Confluence, Notion, Basecamp, etc. We're a team of 20 people right now, and _everything_ lives in Notion. No "look at this google doc" or "go to <vendor>'s website", it lives in Notion. We can link to external vendors for "live" content, but PDFs are embedded, samples are zipped, etc.

Each page has an owner, a contact, and an expiry date. Owner is responsible for keeping it up to date, and if you see a page that is expired you can ping the owner (unfortunately we don't have "alert on expired page" yet). If the owner is unavailable, the backup should be able to answer any queries/update the page, and if they can't then the failure of that lies on the page owner. There are a few pages that have empty backups, by virtue of our company size, but all the critical stuff has an owner, backup and is checked once every month or two.

[rio517]

Our team uses notion as well. We're not at the scale that you are with owned pages , expiry. How does your team feel about the effort-to-value of maintaining it? It seems rather onerous.

We tend to keep more ephemeral project management stuff in our tracker or google docs and more long-lived content in our Notion tool. I'd be curious how your team balances that.

[SQueeeeeL]

I like these kinds of systems. I do feel like in generally they require so much buy in from everyone, maintaining these pages has to be a constant priority. This becomes a problem if multiple people leave at once or someone is very busy when expiration comes up and rubber stamps the renewal with outdated information...

But it's definitely better than no system at all!

[andrei_says_]

I found that Basecamp’s docs are great for documentation.

[r_hoods_ghost]

Hoo boy, that's a tough one. One of my jobs is working for an ISO17043 accreditation provider so we have an ISO9001 QMS that all our docs sit on and every doc goes through an approval process, has a review date on it (6 months, 1 year, 3 years etc.), can have change requests, issues and non conformances logged against it, is included in audits and is written in a standard style.

We have a document controller who's job (not her entire job, but say 20% of her job) is just to ensure that documents are organised correctly, adhere to guidelines and are actually reviewed and updated when they are supposed to be (I.e. she will come and nag you if a document is overdue and you have been ignoring your notifications).

As part of the ordinary rhythm of business, metrics on how well we are doing on the document control front are produced and reviewed roughly every two months by a senior manager in a quality team meeting. If you don't keep up to date with your document control tasks it will be brought up in your appraisal (in a reasonable fashion, you might just have too many docs assigned to you).

There's other stuff, but let's just say document management is quite important to that business because procedures matter when getting them wrong kills people and / or leaves smoking holes in the ground.

Importantly the process of writing a doc is dead easy and anyone (literally, some of the most useful are written by the admin assistants and lab techs) can create one at any time. Theres a standard template and style guide, you write your doc, you choose an approval pathway, classify it and then submit it for approval. While it's waiting to be approved it sits in the drafts register with a warning on it saying not yet approved, but anyone can still access it.

In practice what happens is rather than writing a long email explaining how to do something you'll just write a doc, stick it in the QMS and give someone a link. Then when someone else needs to know that they can either find it themselves or you can just point them at it.

The admin overhead of the whole system is surprisingly small and means that we actually do have up to date documentation on most things.

[IG_Semmelweiss]

Former Notion customer. It failed for reasons that I should have predicted:

Your wiki is always destined to fail if you are never going to use it as part of your daily ops.

This is why our internal wiki with "Clickup" is working OK thus far. We use clickup because it allows us to create tasks from within our wiki and reference docs in our clickup wiki, and link the latter to tasks or even email chains. As long as someone organized is handling the doc repo and the wikis, its quite good.

In summary. Its great for meeting agendas and opening epics or tasks during the meeting so there's accountability (no GDocs). Its great for doc repo that is "alive" to replace Gdrive. Its great to start customer comms (email outbound that threads inside Clickup) within tasks that themselves are referencing docs in clickup. You could also have a true HR / company policy wiki if you wanted, but we are too small for that. Instead we effectively have an OPS wiki. I think Clickup has found a great product market fit within the B2B space. It may even be great for B2C too.

Full disclosure. We are a customer. We make no money from them in any way.

I also bet that Clickup will eat Notion unless Notion does something dramatic.

[fasteddie31003]

This is the exact problem I'm trying to solve with my startup https://GainKnowHow.com .

I think we have been structuring documentation ineffectively for a while. GainKnowHow structures knowledge by prerequisites in a Knowledge Web, which I think is the best way to figure out how something works.

My goal is to let you "program" your organization through skills in a Knowledge Web that represents how your organization runs. You can write tests to see if employees actually understand their skills and there are change management features that tell the relevant employees when a skill has changed through skill diffs.

Here's an example of how to train your software engineers https://gainknowhow.com/software-companies.html

[buro9]

We (Grafana) are just about to roll out https://www.simpplr.com/ internally.

We've been using a mix of tools until now, Guru, Google Docs... but have lacked discoverability, powerful search, and in Google the ability to create sites for teams, etc.

Personally I use Obsidian and the files are sync'd via Syncthing.

What I wish would exist: A markdown driven wiki with Git (or something like it) in the backend so that you can clone the info locally, or refer to the master version, and even stage big changes to an area, etc. - basically something halfway between Obsidian and Confluence I guess.

[discardedrefuse]

I just spent some time looking at this. There's no reason you can't use Obsidian with git. Obsidian just saves md files in a basic folder structure. You can git init in the root of your Obsidian vault directory (.gitignore your .obsidian folder). There's even an "Obsidian Git" community plugin that does the git work for you.

To serve your md files as a traditional wiki in browsers, there's a git backed wiki named Gollum that also uses md files in a basic folder structure. https://github.com/gollum/gollum You can see where I'm going with this.

Gollum doesn't have user authentication or anything fancy, it just renders and edits md files. I tried it. There didn't seem to be a difference between Obsidian's and Gollum's markdown. When I committed my entire Obsidian vault to a git repo, I could still choose to have Gollum serve the entire vault, or just a subdirectory in the repo. I could also disable all editing in Gollum.

While Obsidian is working directly with the md files, Gollum doesn't update until I actually commit the changes. Obsidian is basically an IDE for my wiki now.

I was mostly satisfied with Joplin syncing to OneDrive prior to today's experiment. But now I think Obsidian + Git + Gollum deserves a closer look. It might be a bit overkill for my personal wiki, but it could work in a team setting if everyone works on the wiki like they would a normal git project.

[polote]

Simpplr is in my opinion an inferior tool to Confluence or Notion. It works mostly well for static information and as a enterprise search tool, but won't help improving the underlying culture.

As for you ask, the best solution that I've found, is to let people document things on Github and index those documents in another tool. That way there is no duplication, you let people use the tool they know, can use Markdown, but still benefit from searching, assigning owner, up to date date, rights ... That's how we do it at Dokkument

[jka]

Have you heard of / explored Athens Research[1] (brief summarization: open source, multiplayer-if-cloud-or-self-hosted, YC-backed)?

[1] - https://www.athensresearch.org/

[yabones]

My solution (for personal notes etc) is to make a git repo with markdown files, then render it all with mkdocs on every push. In the past it was just a cron job running on a dumb little webserver (git pull && mkdocs build) to push the new changes every x minutes. Nowadays it's a bit more sophisticated with netlify building on main & PRs. Both are completely valid!

Obviously it's not user-friendly at all. Only people who know how to use git can use it, which isn't great for collaboration with non-techie folks. Ideally, I'd build a little editor widget that could be embedded in the page...

[dotancohen]

  > A markdown driven wiki with Git

This is exactly what I do. Though lately I've been transitioning to org-mode for non-personal notes as I don't need them on mobile.

Your users can use any Markdown editor that they like. But one person should be responsible for creating new documents, so that there will be consistency in naming and placing in the hierarchy. Naming things is hard, leave that part up to the Knowledge Base owner.

[tempest_]

WikiJS can store its files in git (https://docs.requarks.io/storage/git) though it is not exactly easy to run as a stand alone app.

[therealasdf]

AzureDevops wiki is exactly that. A git repo for markdown files

[pxtail]

For some documentation we are using https://www.bookstackapp.com/ , we have also few instances for clients internal docs.

What is especially nice (less for us, more for some of clients) is that it has clear, understandable and working out of the box ACL system in place - and this is not obvious or easy to setup/configure for many wiki-like projects out there.

For maintenance and filling knowledge-base - I think that what's works for us is establishing and following rules, for example: one cannot mark feature as complete without creating/updating documentation page related to it, documentation maintenance is checklist element of task completion flow.

[pabs3]

The Diátaxis documentation framework is one I heard about recently, Ubuntu/Canonical are switching to it:

https://diataxis.fr/ https://ubuntu.com//blog/the-future-of-documentation-at-cano...

[hdjjhhvvhga]

Old style - an "intranet" wiki that is linked to from the main internal company page. No orphaned articles - each needs to fit in the hierarchy somehow that is obviously quite flexible. Searching is easy and gives instant results. As opposed to the current version of Google, you can use search operators and they work as expected. Because managers embraced it and encourage their reports to (actively) use it, it works - most of the time.

The biggest challenge is outdated information: since the responsibility is shared, sometimes I come across articles that haven't been updated since 2011 - for example, because somebody left, and I see some bits aren't up to date anymore. But I feel uneasy about deleting the article or just doing anything about it unless it's one of "my own" or directly related to my department. But in spite of that, I think it's working quite well overall. I used Confluence in another company and it felt too invasive and in the end nobody used it.

[hifikuno]

Unfortunately I think we are stuck with Confluence. I don't have the sway to change software.

To help with finding things we are using a slightly modified implementation of the Johnny Decimal system (https://johnnydecimal.com). That's one of the news things I have implemented.

I like the idea about no orphaned articles, I think we have a few of those that need to be placed somewhere. Pointing out that responsibility thing is good, I'll have to make sure that we change our attitude a bit towards that.

[amattn]

I'm working on a solution to this called KB Clip: https://kbclip.com

basically it's a slack add-on that allows you to turn a conversation into a web/wiki page in just a few seconds. Essentially, lots of important, KB-worthy info happens naturally during the course of work slack conversations.

The idea being that making knowledge capture easy kind of naturally makes the usage of the knowledge base happen. KB usage is kind of a chicken and egg problem. if no one creates info, no one will look there.

We don't currently export to Confluence, but the plan is to export to most of the major wiki/KB platforms. We're going thru Slack App Directory approval process at the moment, but we're planning on doing a big marketing push as soon as that happens.

happy to answer any question about this topic or the product we're building!

[fsloth]

"It's hard for me to just work on the docs as I feel like I should be following some sort of standard as I do it."

Some standards come to mind: Microsoft's Style Guide (https://docs.microsoft.com/en-us/style-guide/welcome/) and Strunk&White's "Elements of style"

But if you feel writing should have standards, then you might to need to write those standards yourself. Which is not a bad idea at all - you just need to approach it as a journey of discovery - which standards are helpfull, and which are not. It's not something that can be got exactly right from the beginning.

Github's issue reporting functionality fills in automatically content hints.

Maybe you could start from headline template with content hints, and evolve that as need arises?

[turkeywelder]

All the business knowledge is in Basecamp as that's where all the "work planning" is done. If you want to find out how a specific feature works, or how the decisions were made for that, go find the project in Basecamp, it'll be archived if it's shipped but it's still searchable.

For new dev setup/infrastructure stuff we use a github Wiki and the new starters point out issues in that for us - their first tasks are to update it if they find issues or missing info because it forces them to go and dig around to find the knowledge islands - they're the best people for it because it's who we want to solve the problem for.

Admittedly we've got a small company and a nice tight tech stack but there's still tribal knowledge in 2-3 people's heads and distilling that out to the team is a slow process of pair programming and explanation.

[furstenheim]

I've always found that wikis are too far from the code.

To have any chance of being up to date, knowledge of the code and functionality should be as close from the code as possible.

[luka-birsa]

We're happy users of Confluence (SaaS version) and try to store all knowledge there. At 50 employees we have multiple teams approaching the Confluence as a KB with various success so there are a couple of takeaways.

1. You need to mandate that everybody uses one tools and push for the use from the top down as well as showcase the use bottom-up.

2. Split responsibilities on a per team level; eg people working on product lead the product confluence page, people working on hardware lead the hardware confluence page...

3. Try hard to push all relevant discussions and decisions to the same KB.

4. Request that leads schedule time for updating knowledge base (we sometimes push for this via OKRs).

5. When people are leaving the company, we primarily push that they update the KB to the maximum (other work is not important after they give notice).

[thrower123]

A succession of wiki products that are essentially write-only. No one ever reads them. Eventually somebody gets frustrated with the disorganization and says "We should switch to Yet Another Wiki Product" and the cycle begins anew.

[adrianomartins]

I feel we've been in the same spot as you. We had a wiki (google sites and google drive with a lot of documents) but information would become inaccessible from time to time, to the point it was pretty much useless. We eventually understood that the knowledge sharing/maintenance was simply being an extra step in our work, a mostly disregarded one, almost an after thought.

What we did was to put knowledge at the center stage, make it as easy as possible, pleasant to maintain, and avoid at all costs new/extra tools. We eventually settled for Notion. I'm sure you can find about notion benefits on your own, but essentially it does all that. It's super intuitive, easy and beautiful, easy to get around (albeit sometimes slow). Get everthing in the same place as much as possible, with every new tool you'll loose out (knowledge bits here and there, extra connections that stop working, or that people don't bother to check)

But getting a good information platform was only half of the story. We needed to start thinking and working differently. We decided that if we ever make a decision, or arrive at a conclusion, that's worth sharing, then it should be worth writing. And it's by doing this, and expecting all other team members to do it as well, that we arrive at this stage.

I'm sure this doesn't work for all teams, and other teams probably arrived at other, even better solutions, but this was what worked (wonders) for us.

[hifikuno]

I have used Notion before personally and it's a sweet bit of software. We're already an Atlassian shop, using Bitbucket, Jira and Confluence. Up until very recently we were barely using any of it but my team just moved from SVN to Git (about bloody time) so when we started using Bitbucket it started to ball rolling with the rest of the stuff.

I like the idea of any sharable decision or conclusion needing to be documented. We are a data warehouse for our organization and so we rely on business rules ALOT. So many of those business rules live only in the code with no explanation and no one remaining who can explain it.

I think we're at the turning point of beginning to think and work differently. I'm going to start with my small team of three, and once we get going then try expand it to the rest of the department. It is kinda hard as I don't really have the authority to enforce it, the best I can do is strongly suggest.

[blindluke]

> My problem is, I know that we are missing information, what I don't know is how to tease out that information from myself and other coworkers.

I would start by reflecting on the way in which getting that knowledge out of the coworkers into the knowledge base is incentivized.

I keep my notes in markdown files. A lot of my coworkers use Obsidian, CherryNotes, OneNote, and I'm sure that there's a dozen other solutions out there. Keeping notes locally is actively encouraged by the fact you can't rely on the Confluence server to be up after business hours and the fact that the centralized knowledge base upgrades destroyed our documentation efforts twice over the past 10 years.

I also keep my notes short, omitting everything that's obvious to me. This makes them less valuable when it comes to knowledge sharing, but makes them better for me - short notes mean less visual noise to filter out. Writing a version of those notes that's more comprehensive is extra effort. That extra effort needs to be visible, treated as 'real work', encouraged and valued. Otherwise, I will prioritize other tasks that are visible, treated as 'real work', encouraged and valued.

The first thing I would worry about is making sure the central knowledge repository is as convenient as the local notes. Then, I would examine if creating / updating documentation in the central repository is encouraged, and in what way.

[nickjj]

I use Obsidian for my own notes that only live on my machine, then they bake there for a while until they get refined enough to turn it into something that others can read in which case it gets published within Confluence.

Personally I'd rather see a knowledge base that is in pure Markdown, perhaps a static site that auto-publishes on push to a specific repo. I just like the idea of being in control of the text, plus it means you can write these docs in the comfort of your editor instead of using a slow web UI. Right now I end up writing it offline and copy / pasting it along with formatting it in Confluence afterwards, it feels like a little wasted effort.

We try to reserve these types of docs to be guides, it's more like blog posts not so much a detailed instruction list on how to use some library or app. This way they don't really get outdated because a library or step changed.

I'm a big fan of never deleting guides and notes though, for the not needed ones I'd still keep them around but maybe move them into an archive section. Really, a static site generator has all of the tools to make a really nice system for this. You could also spend a day to make a little back-end to offer full text search too.