Wiki Way - Documentation without Documents

The environment we work in is highly integrated and involves massive amounts of collaboration. We need networks of related information, but our tools encourage documents that are monolithic silos of obsolesce.

The requirement I gather may be reused by another project in a different system, my definition of a "Customer" is going to be reused by three different projects, my project will impact some functionality that will later be impacted by three different processes, and all of the information in "my" documentation is going to have to be re-read and re-written by a horde of others.

Integrated solutions, silos of documentation

So what we should have for documentation is a collection of discrete pieces of information, shared between projects, systems, departments, and people, referenced from a multitude of places depending on need. This is a Wiki.

What we actually have is a graveyard of monolithic documents that are an arbitrary collection of information based on whether they were written at the same time, that only one person writes, and (if you're lucky) one group will read once. This is documents on a share drive or even an ECM.

Our whole environment is so integrated that a single business process could have come out of dozens of projects, crossing many systems form disparate projects, why shouldn't it call come together in one cross-linked place?

Documentation is great, Documents are bad

Every time you cut and paste from an old document to a new one you are not only wasting time but you are implicitly throwing away everything in the old document for reasons I mentioned a while back.

We have to communicate the same information to many different stakeholders and we assume that we know best every time we pack things together in a "pack" - but it's just plain Hubris to think you know best what others need to know. Best to put everything down and let them pick.

Long Lived

More than %80 of the solution definitions put in documents are never used again because by the time they become the main focus so much of the context around them has changed that the whole document is out of date. You've got to make it easy to change little things about items you impact in the main place they are documented if your information is going to live past you. Wikis make this far easier.

Modern Wikis have so many easy to use funky tricks to re-use and summarize content in different places that you'll be amazed where information ends up getting re-used and read, and if it gets read the chances are that it will get updated.

Presentation not Layout

Most word processors are just plain bad at letting you focus on content. The fact that a Wiki takes you back to paragraphs, headings, bullet points, and table is a strength.

If you want something pretty there are ways to do it, and if you want structured content there are also ways - but my advice would be get back to basics and concentrate on what you want to say not font or bullet points you use to do it.

Separate Project from Prosperity

What absolutely kills any hope of information re-use in documents is that most SDLCS don't differentiate between information needs for the project and for prosperity. You project scope ends up including system scope as well, your test cases include a list of test run along with the long lived definition of test-conditions. This is just crazy but there's no way around it as long as you have to produce a pack for sign off using a document.

I think issue tracking systems are pretty nice here also - but that's a different conversation.

Collate to present

When you have all of your information out there modern Wikis make it trivial to bring it together into one page/place to present for sign off. You don't need to change your deliverables to use a Wiki, you can just generate the content the Wiki way and then collate as needed. Then every time you change the system description all of your deliverables are auto-magically up to date (As well as any other projects that may reference you)

This still one of Wikis weakest points for software development. It takes some trickery to store a point-in-time version of a page but it can be done. The pages you end up creating can also be pretty ugly but I'm hoping somebody (Are you listening Atlassian?) will produce output as good as the PDFs form Wikibooks.

Easy

Seriously easy. I'd say it's easier to switch to Wiki from Documents than to switch to a new set of templates; especially for a younger workforce.

Don't let it just be IT

Chances are if you have a decent sized development community there's already a guerrilla Wiki effort going and there's a real temptation to make this an IT tool, or have separate IT and business areas. That's a mistake.

Wikis have such a network effect going though that by playing nice with others you'll get amazing returns. Business users, process owners, HR people, canteen managers, all have parts to play. Having the deep context about the business linked in with the IT information is what will keep you aligned.

Not all Rosy

It's not all rosy though, we've used documents for documentation for a long time for some pretty compelling reasons. They're convenient, a trusted metaphor, have fantastic control, easily printed, and easily shared by email.

Step away from the requirements/design tool

Heart on my sleeve time, I don't believe in tools.

They over-structure everything, lock you down into their way of doing things, over-organize their own domain and neglect everything else, and make ivory-towers where the tool-user condescendingly "publishes" out information to the plebes who don't have it installed.

Tools get mis-used as a best-practice or process-improvement piece. I've never seen this work. BAs or Architects without the skills or processes needed are still just as ill-prepared with a tool. Spend the money on putting a copy of the BABOK Wieger, Cockburn, and Gottesdiener on everyone's desk instead.

The high-end Tools are also incredibly expensive to buy, maintain, install, support, and train; and once the vendor gives you the first taste you'll always need just-one-more-product.

Next Steps

I wish I could point to a sample of a Wiki showing a business' architecture and systems but I can't. Next big post will be give a rough structure of what you could start off with.