The Product Vision blog

Requirements docs: Goodbye word processor, hello wiki

Monday, June 22nd, 2009 | tools | 5 Comments

Product managers like Ivan Chalif of the Productologist Blog are justifiably tired of the fat MRD. Ivan make the case for 5-10 page release specs docs.  Here I would like to make the case for discarding the word processor and using wiki’s instead.

Ivan points out that elements like the business case and competitive analysis are irrelevant to audiences like engineering.

While this is true it is still very important to capture that information. They state the assumptions behind the product vision, and while the engineers may not care about it, they are extremely relevant to anyone who needs to scrutinize the product vision.

There are other fundamental problems with fat documents: they are extraordinarily laborious to produce. Especially the part about finishing it: having to comb through it carefully, finishing each section, and trying to perfect it for the momentous occasion of publication.  Readers will only read it carefully once (if that), and minor errors can damage its credibility and distract the reader from the critical messages.  So the fat document has to be very high-quality, and that means some very late, and burnout-inducing nights indeed.

A couple of years ago, I underwent the most significant change in my toolset in years. I switched from word processors for such documentation to wiki’s.This had a number of huge beneftis:

• The documentation is more useful because each audience can read only the sections they need to. Business managers can read the business sections, and the engineering staff can read the product requirements sections.
• The publish cycle is streamlined.  In the word processing world, everyone waits while you write and perfect the MRD. They provide comments, you incorporate feedback, and publish another fat version of the document. And possibly another, by which point everyone dreads having to read your document again. When you pass in the halls, people avert their eyes out of guilt for not having re-read your master work.
• You are now free to build up your document from rough notes that are incomplete or not 100% baked.   With wiki’s, the whole ritual of document creation is changed.  The document is always published, even in rough form, even when it’s just a skeleton.  Everyone understands that the  document is never “finished;” it is always a work in progress.
• The document can be created in pieces.  You can put out a section for comment while you work the next section.
• The document becomes a group conversation. Reviewers can comment to each page and can react to one another’s comments (unlike change tracking in word processors).
• It’s much less daunting for a reviewer to re-read just the sections they care about, than a fat word processing document.
• The document is always up-to-date.  You can incorporate someone’s comments immediately, even while meeting with them.  Everyone always gets the most up-to-date thinking available. They don’t have to wait for the next publish cycle.
• Wiki’s are hyperlinked. This means less repetition, and it lets the material scale to the needs and interests of the reader.
• Wiki’s can be created collaboratively. Different product managers on a large project can own different parts of the MRD. And any reader can jump in and fix typos or make minor edits.
• Wikis are globally searchable.  Old but valuable information is findable.
• No more wasteful printing of hundred page documents
• And you don’t have to throw the baby out with the bathwater. You can document everything that needs to be documented. You don’t have to arbitrarily excise important information just because it makes the documents too cumbersome.

This approach just so happens to be the Agile way of doing documentation: put out something small but something useful quickly, and keep adding and refining it.

My wiki of choice these days is Google Sites.  While it’s not without its quirks, the net benefit over word processors is so great that they are tolerable.  The greatest downside is that the information is hosted at Google, not within the secure confines of your corporate firewall.  This may or may not be a deal-breaker.  [Readers, is there a clear favorite intranet wiki that deals nicely with rich text and graphics?]

If you are still publishing word processing documents, give a wiki a try instead!

See also:

• Top 7 Tools for Interaction Design and IA

—

Philip Haine is principal of Product Vision Associates, a product innovation consultancy that helps product leaders and their teams envision new, breakthrough products and reboot older ones.  To follow him on Twitter click here.

Tags: documentation, requirements