
Ask HN: How to encourage and maintain a long term organizational knowledge base? - smellfungus
We, as many others, use Slack to communicate. But this only works well for real time and short term projects. Those teams that do document stuff for the long term, either does it poorly (structural, and does not maintain it) or uses different services (Google Drive, Quip, Dropbox, different wikis, etc) more suited to their needs. I&#x27;m both talking about high level technical documentation and organizational documentation. This makes it hard do on-board new people, hard to get to know other parts of your organization and hard to search for answers without bothering others.
I really want to hear from you what success stories you have growing a documentation oriented culture and what others can do to encourage the behavior.
======
mattgibson
Currently, after trying quite a few other things (Basecamp, Confluence,
READMEs, just not bothering to document things), we've now settled on using a
simple git repo of markdown pages which auto deploys to a mkdocs site from
master.

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
    

Using tools that are already familiar to the team has been a big win. People
are enthusiastic about this solution in a way that they never were about the
others.

------
castillar76
It took us forever, and it's still (and probably always will be) a work in
progress. But a couple key points for us:

\- 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.

------
MMQcsvn6128
No matter what you do, you have to solve what I call "The Documenter's
Dilemma" or nothing will end up working long term.

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.

------
evolve2k
I don’t have all the answers but personally I keep coming back to a shared
wiki, current approach is a private GitHub repo called companyname-guides and
the README just said click through to the freely available wiki in the repo.

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.

------
codingdave
It sounds like you already know the answer - you need a single persistent tool
for documentation that is open to all for reading and editing. It doesn't
matter what that tool is, just that it exists, and that you build an
environment where keeping it up to date, and using it, are a core part of your
culture.

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.

------
musha68k
Anecdote: I know "the right tool" is not the answer usually but suprisingly
enough the introduction of [https://slite.com](https://slite.com) (ditching
confluence) has helped our team in pushing us further towards a "document
first" path / culture.

------
tmaly
I picked up a book on Organizing Knowledge at the company level. I definitely
think it is a helpful topic to read up on.

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.

~~~
jcgr
Could you tell us the name of the book please? Thanks!

~~~
tmaly
Organizing Knowledge: Taxonomies, Knowledge and Organizational Effectiveness
by Patrick Lambe

------
domtron_vox
Ironically I'm rolling out a new documentation initiative at my workplace this
friday after about a year of work.

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.

------
d2clon
In our organization we have been dealing with the lack of documentation (or
chaos on it, what it essentially the same) for long time already.

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...](https://meta.stackexchange.com/questions/16054/is-stack-exchange-
stack-overflow-available-for-private-or-internal-use)) we decided finally for
its younger brother
[Discourse]([https://www.discourse.org/](https://www.discourse.org/)). Mostly
because it is open source and we have the possibility to keep my so extremely
costly generated content in our house and not been hook to any company. At the
beginning we are using the hosted version for convenience though.

We are in the beginning of this process (3 months), for now everybody loves
it. We are trying to build the habit that every time someone asks something
(by email, slack, ...) we ask to create a question in our Discourse and we
answer it there.

------
zachguo
Stackoverflow Team + Wiki

