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