Content independence

Today's post from Tom Johnson of I'd Rather Be Writing talks about "content independence" and how a wiki can help you achieve it.

Tom's argument starts with this observation:

• Authors need to update documentation after release.

This is because documents have bugs in. They have more bugs in than they might, because authors don't get time to fully check their work before release. OK so this really means

• The time required to create full documentation with no bugs is too much for a project manager to include in the plan.

Why's this? Because the product is ready; we need to release it or risk being behind the market. But we spent a lot of time in QA fixing the bugs in the product; why are bugs in the documentation worth any less to the project manager? I think there are two perceptions at work:

1. Documentation is not absolutely essential. The product is "good enough", and will work even if nobody knows how to use it. In the worst case, we can send a support engineer over to the customer to make it work for them.
2. Bugs in documentation are easy to fix. Most problems with documentation don't require a complete rewrite of large chunks of material, whilst bugs in software can sometimes be traced back to bad design assumptions and lead to large refactoring projects.

Also, and because of these two:

• Fixes to documentation bugs don't need testing. Because of 2., the fix has already been adequately "unit tested" by the writer, which is normally enough, and because of 1., the product won't break if we incorporate it.
  

And because of this:

• Documentation doesn't need release management. Project managers allow authors to provide what they can with the release, and fix later.
  

This is where Tom comes in: working in this environment, he naturally looks to wikis and other online tools to make fixing easier. But there are environments where the core assumptions don't hold, for example:

• Correct documentation may be a legal or contractual requirement. In some fields, particularly safety-critical ones, the documentation must be correct on the first try. Many clients like to see full lists of changes to documentation as a condition of acceptance. This breaks assumption 1.
• The supply channels for updates may be limited. In a world of wikis, we forget that people still naturally turn to the materials provided with the product when there is a problem, if only to find out where the wiki is. Also, some products are used in situations where it's impractical to check online for changes to documentation. (This leads to situations like of "If your modem is not working, check our website for instructions".) Again, this is assumption 1 failing.
• Documentation may be widely translated. A small change to a document may require weeks of sending round to multiple translation agencies to implement it. This breaks assumption 2. (Though if you don't mind some translations lagging behind the "native" documentation, you can split the task up so that it's not a problem.)
  

Ultimately, whether or not documentation should be release managed depends on the product and its position in the market as much as on the documentation itself; but authors often end up making this decision on their own.

In my company, as for many smaller software businesses, I think the assumptions hold, and I'm working at establishing an online knowledge base which is updated independently of the release process. I hope that it won't take me five years to get the idea past IT, though.