TL;DR Aspiring tech companies invest a lot of time & effort in the latest frameworks, most hyped platforms or hippie operating models, while in the same time their so-called knowledge management is taken straight from the 80s. It's the highest time (if you haven't done it yet) to give up the world of "documents", "forms" & "sign-offs" for the modern paradigm of collaboration-based knowledge bases.

In such a complex industry as building software products things that may have worked for one company may be completely not appropriate for another one, or in other words: one company's greatest mistake may be a bulls-eye for another one. However, there seem to be some common practices that are pretty much A-MUST-DO/HAVE for every software engineering work environment, but still some seem not to notice their importance & openly neglect them. No, I'm not going to write about "the usual suspects" - Continuous Integration or test automation. The topic for today is much more inconspicuous but still very important - Knowledge Base.

Let's put aside the whole discussion about documentation in general: how extensive it should be, documentation as a side effect, documentation based on metadata, living documentation, documentation as tests, etc. The important thing is that at some point 99% of the organisations come to the conclusion that some sort of documentation is needed. Unfortunately, many of them approach the problem in a very wrong way - one that escalates difficulties in making good documentation & multiplies the effort to keep it up-to-date.

Annoying duty

Typical documentation I've encountered in my past endeavours is like that:

• it focuses only on the "delta" (detailed instructions of what should be changed) -> so to retrieve "to-be" state you have to get initial "as-is" (from the first release) & apply all the relevant deltas (you need to find them first!) on the top of it
• it's painful to collaborate on in parallel -> typical form (Word document, PowerPoint presentation) is suitable for one person working in exclusive mode (who then sends it to the next one in queue ...)
• it's shaped for single, one-off receiving -> contains encapsulated content fit for one context & limited group of people (e.g. tech reviewer + developer); hence it's barely re-usable

Once the review and / or implementation is done (by the manager, architect, review board, etc.) document is archived & pretty much forgotten. It doesn't bring any more value as it content gets almost immediately outdated & the number of pieces you need to assemble to get a full picture back grows too quickly.

Does it sound like helpful in building up the actual knowledge capital within the organization? Exactly.

Social scribbling

But what if you stop thinking about documentation as artifacts, filled templates or sign-off forms ... Why not treat it more like a living collaboration platform, organic Knowledge Base, an effect of everyday social contribution of people who input, groom, fine-tune, adjust & update information vital for all of them?

YES, you've got it right - think about your local clone of Wikipedia's underlying concept & the benefits you can possibly draw out of it:

• formal review cycles & change cadences are not needed - everyone can work on in "continuous mode" as reviewers / interested parties can subscribe for changes of the content relevant for them
• contribution has minimal friction, so there's low mental barrier for starting - nothing is carved in stone, revamp is easy, so it doesn't feel like a big deal ("ceremony"), but more like adding side-notes to the code
• it grows organically with solution (in correspondence to its structure) - it doesn't have to be linear (which is often confusing), but rather consists of a mesh of interconnected & related "articles", "notes", "entries" - each of them associated with real artifact, entity, work product, etc.
• encourages & supports group collaboration in real-time
• focuses on the up-to-date snapshot of the product / system, but enables rich annotation of the content to track its different dimensions (e.g. changes in time): not only versioning, but also tagging, categorising, marking with attributes, etc.
• is easily "navigable", traversable, searchable -> so you don't have to follow author's "path of thought" to get something out of it

Can you get any of these from shared directory with the stockpile of dated Word documents?

Knowledge Base != tool itself

The difference between these two models IS massive, but somehow many (even highly aware) organisations fail to implement the latter model. The truth is that building a successful Knowledge Base is not a matter of deploying a tool (presumably some kind of Wiki), but building up a proper culture of knowledge sharing & contribution:

1. by setting an example
2. by clear appreciation (message from the executive level) of effective forms of knowledge exchange
3. by indulgence for first (likely awkward & uncertain) steps
4. by consistency (this is a platform for everyone, there are no command mode memos or requirement litanies from the resistant)

It is not an easy path & succeeding may require a lot of effort & time, but if you don't pick up this challenge, aren't you insta-failing?

Pic: © tashatuvango - Fotolia.com