Wednesday 22 March 2017

The three stages of a dev wiki

First They Ignore You
A well-meaning dev sets up the wiki on a spare server. It contains some important information about the network that nobody else understands, a very terse guide to application architecture, a page about local bars and restaurants that is, somehow, already out of date.

Then They Like You
Very gradually, through dint of a handful of well-meaning devs continually suggesting people add things to it, it grows. Useful information about how to set up environments is added, as well as how to debug more complex problems.

At some point it reaches a tipping point of usefulness and becomes the defacto place for documentation. Reams of notes from meeting, observations from research spikes, and ideas from brainstorming sessions are added, large parts duplicated and contradictory. It is chaotic but a goldmine. The page on local restaurants and bars is never updated. Only one of the bars is still in business.

Then They Ignore You Again
Eventually the wiki comes to the attention of upper management. Maybe Support. Maybe Sales. Maybe Ops. Somebody sees it, sees that it is good, sees that it is a democratic nirvana to which everybody can contribute and nobody has overall control, and decides it should be theirs.

They institute a Wiki Transformation Project, which despite being a glorified database migration somehow takes six months to complete. When finally complete it is introduced with a company-wide powerpoint presentation (attendance mandatory).

The new wiki is on some more intimidating platform: Confluence maybe, or Sharepoint if you are really unlucky. Half the users do not have permission to edit pages they wrote themselves. All of the formatting is screwed up and several important diagrams and flow charts have been lost completely. The page about local bars and restaurants has been quietly deleted along with, it becomes apparent only later, a number of other pages people relied upon. Only a handful of well-meaning devs ever add anything new to it again.

No comments:

Post a Comment