Ask HN: How to encourage and maintain a long term organizational knowledge base?

My process has been to be deliberate any time I’m teaching someone a new skill or process. Either I tell them, wait a bit I’ll write something up first or I review the existing page and then we go through it together. That way updating the knowledge base becomes part of the standard knowledge transfer process, I think that’s the key.

Once we start that way it’s also made it easier when I’m quickly retraining someone and I say now can you add that to the wiki page. For them it’s not some random page it’s a page we worked on together and they seem much more confident then to go in and change it.

You can have a wiki or Confluence and still not be able to find things in your company if things are not planned well and a decent ontology is constructed.

We have this set up to require merge requests on GitLab to be approved by two developers and for each new merge request to appear on Slack via a webhook when it's opened.

This has been extremely effective because we now have:

  - History via git (better than a simple wiki)  
  - Simple diffs because markdown
  - Immediate visibility of upcoming changes via Slack
  - At least two other developers forced to actually read the new page(s) before they are added
  - Nice HTML/CSS via the material mkdocs theme, which we can easily customise

- We established a single wiki for our department, and gave teams control of their own spaces. One wiki in one place with full-text search means that if the document exists, you can at least find it.

- We followed that with an organizational mantra: "If it doesn't exist in the wiki, it doesn't exist at all". If you have any kind of docs, they go in the wiki. Crucial to success here was using wiki software that would take Word docs, Excel spreadsheets, graphics, etc. and just attach them to pages and optionally render them. (We used Atlassian Confluence, but YMMV.) This meant that if you had the docs, there was as small as possible an effort involved in placing those in the wiki where others could find them.

- Periodically, we have Friday 'wiki burn-down days', where we buy pizza for the group, huddle in a conference room, and spend the day in the wiki. We write articles, we clean up spaces, we fix up documentation.

- We experimented with having new engineers work with senior ones to write documentation. This was OK in some regards--it did help them be exposed to more things, and encouraged more senior folks to explain things and answer questions to write the articles. But it definitely takes time, and wasn't as useful as an onboarding exercise as we would have liked—depended a lot on how well the senior person could explain it, and how well the junior person knew to ask questions about it.

I'm using mediawiki with quite a few extentions to meet our needs.

I designed the structure around use cases since the documentation is for me and my coworkers to make us more effective. I'm also making it clear that if they have any issues or frustrations to contact me and I'll try to fix them quickly. I.e. lower the bar as much as possible to get people to use it.

As a general rule if someone is asked a question (internally) more then twice it should be documented to help save them time.

For our structure we use a heavily formatted main page with the 1st half focused on handeling emergancies, req/report forms, and general quick links. The 2nd half categorises all pages into 3 functional groupings. Guides to handle step by step process pages, notebooks for longer explanations for training etc, and referance for lists/tables of data.

These are then further divided into department focused groups.

Tl;dr IMHO do a bottom up design based on use cases like emergancies, quick lookup, normal day to day tasks, edge cases, etc.

Let's presuppose an already-functioning documentation system, and three types of organizational players: the "Outstanding Engineer" (OE), the "Grinding-style Middle Manager" (GMM), and "GMM's middle or junior Engineering staff" (GES).

Imagine the following scenario: OE, a true believer at this point, authors an outstanding and informative technical document as an act of pure goodwill. OE is a busy person, with sweeping responsibilities that are often not completely understood organizationally. However, so far, so good, and different OEs across different areas jump in with articles of their own, often for areas they are not even officially involved in.

Meanwhile, GMM is directing GES to digest and leverage these documents to their fullest extent. Note that neither GMM nor GES could have authored the documents they are leveraging.

The Documenter's Dillema is this-- over time, the occurrence of one or more of the following is completely certain:

1. GMM or GES argue successfully that the LACK of an OE document is "the problem", for whatever "the problem" is that day, and that the solution is to force OE to do something about it.

2. GMM and GES successfully sustain a multi-week, widely CCd email thread that includes OE with the implicit expectation that OE monitor and react quickly to developments on this email thread.

3. GMM or GES argue successfully that because a procedure documented by OE does not work anymore, that this is some type of "external critical blocking item" blamable to OE in a status report of some type.

OE types are not OE types because they are stupid. They quickly understand that none of #1-3 would have occurred if it were not for their initial act of goodwill. Therefore, OE types will entirely cease to contribute out of goodwill, and mostly cease to contribute unless strictly necessary, upon which the contribution will be the minimum possible to minimize the damage.

Unless this is recognized and explicitly corrected for at the very top of the organization implementing and consuming the documentation, The Documenter's Dilemma will appear every single time.

At the beginning I was the first one in opposing in making too much investment in documentation, mostly because the amount of resources needed to keep documentation updated was overpassing our capabilities. And I consider that an out-of-date documentation is worst that not having documentation at all.

But we are growing, new people is joining us every month (week) and they feel completely lost, and the same questions are arriving again and again, and there is not any central person to ask all of them.

We decided we have to invest in documentation.

And, I, as the technical responsible, started taking this very seriously. I staid full days creating pages and pages of documentation about our systems and how to operate with them. I was using Google Docs just because it was easy to use at least to create the first version of it, then, when the structure of the documentation was emerged, I would think what would be the most appropriate system to allocate it for the long term.

Working on this was not very rewarding. I found my self writing detailed information about things that maybe none was gonna read ever. It was a very solitary work because even if any one could contribute to it it is difficult to distribute the work, specially at the beginning when the structure was still not defined. The velocity that our system was changing and growing was faster than my velocity in writing documentation, making it impossible to feel that I was doing any progress.

And above all, for me (and most of my colleges), writing documentation was a very boring task.

Then we changed completely.

How can we make the documentation generation an engaging activity?. How can be sure that we are writing the documentation that is needed and no more?. How can we involve everybody in the creation of our knowledge database?. How can we make sure the information is accessible?

Then we think in the Question/Answer systems.

Where do I go to find solutions to my problems when I am stuck in a programming issue? In what place I have collaborated the most in sharing knowledge with others? What place makes me feel good spending time sharing knowledge?

I am talking about StackOverflow.

We thought we need something like this to our documentation problem.

There are many things that makes this an obvious decision:

- Documentation is created "on demand": some has a question and someone else answer it. So the documenter knows that she is helping someone, a concrete person. Making it feel helpful with the immediate reward of the recognition.

- Everybody can create documentation: These systems doesn't require any technical skill, they have nice interfaces, they are build to remove any friction in the generation of content: styling, uploading images.

- Not structure: You don't need to think where to put this piece of information. You don't need to follow an index. Maybe a bit doubts with the category or the tags, but it is minimum

- Information is accessible: these systems have a very nice search engine that allow us to not only show you results of your search but also pointing you when you are asking something that has been already answered.

- Information is sharp and to the point: I have a question I want a concrete answer, I don't want to read a full theory article about generic information.

- It is funny: some inner gammification mechanisms make us feel good when we interact with the systems.

We were looking for different systems and even I love [StackExchange](https://meta.stackexchange.com/questions/16054/is-stack-exch...) we decided finally for its younger brother [Discourse](https://...

As far as how to get that culture, it starts with constant reminders. If someone asks a question in slack, answer it via documentation, and send the link in slack. If people send you long answers or explanations, ask them to put it into the tool. When people come on board, give them access to the tool and see how far they get before they get stuck... then add answers to whatever questions stopped them.

It doesn't happen overnight, but it doesn't take years either. A few months of solid focus on just doing it, and you'll be in a better place.