It's really time to DRY our apps' Knowledge Management!

While I was reading the amazing Pragmatic Programmer manifesto, several years ago from now, I really enjoyed the "Keep Knowledge in Plain Text" principle (tip 20).

Unfortunately, I never really took the time to apply this principle seriously for the Knowledge Management (KM) of the various projects on which I worked. Every time, I lazily put all the team/application related informations whether in a wiki, or as MS Office documents stored on a Sharepoint... (sad panda ;-)


Last time, while I was having a lunch with a colleague of mine (a well-known and passionate french craftsman), I realized how lazy I was so far regarding this KM topic. With 2 or 3 words only (read-only wiki, Markdown documentation, SCM), Cyrille starry-eyed the dormant craftsman in me.

Indeed, since:

• wiki web sites for DEV teams usually finishes badly (e.g.: lots of different wikis/sections for the same component/teams, no proper knowledge of what is still relevant and what is deprecated, structure mess, etc)
• documentation created separately from code or components is less likely to be correct and up to date
• it’s not easy to compare/diff MS Office documents
• it’s important for every piece of knowledge to have a single, unambiguous, authoritative representation within a system (DRY principle)
• the text documentation has becoming more important than ever since the advent of the blue book (to express the ubiquitous language of our projects, to clarify some large-scale design intents, etc)

It would be a good idea for us to find a way to get rid of traditional team wiki site, and instead to write every documentation in:

• text files written in Markdown format (we may benefit from any Markdown existing tool/editors)
• stored within the SCM of our project (e.g.: SVN, git)
• and to make our Software Factory (re)generate a static web site (like a read-only wiki) every time we changed those Markdown text files from within our SCM. 

As benefits, our team/application documentation will:

• always be up-to-date and versioned
• easily diff-able (text files with Markdown format)
• respect the dry principle (with our SCM as its golden source)
• easily browsable by everyone in a readonly but readable wiki-like web site (DEV, QA, Support teams, …)
• easily modifiable by team members in a well know and official location (as easy as creating/modifying a text file in a SCM)

Of course, the idea here would be not to reinvent the wheel, but to reuse any existing Markdown renderer & static web site generators instead (the step beyond the github Readme.md file). But if I can’t find something and make it out quickly, I would probably initiate an open source project to implement such system.

Cyrille was right: it's probably time for us now to kill wikis! and to reinvent them.

Last but not least: a very interesting post of Cyrille about Collaborative Artifacts as Code.



BREAKING NEWS: I found a solution for my use cases, described here.