the ryan king

Paul M. Jones has a great blog post entitled Wikis **Are** For Documentation. He says:

This stand [that wikis are insufficient for documentation –ed.], in my opinion, addresses the wrong problem. My basic rebuttal would be that PHP userland lacks not merely “robust”? documentation, but that it lacks “almost all”? documentation. The key here is not merely to improve the state of existing docs, but to get **any** docs to exist in the first place … and wikis help with this tremendously. They are not perfect, but they are a great start to get some docs out there.

Paul’s writing in response to Sean Coates, who says Wikis are not for documentation and makes a strong argument that low-barrier to entry collaborative writing that enables quick iterations is a great for documentation writing, even at the expense of structure.

Of course, just because you don’t require structure doesn’t mean you can’t allow structure. Technical documentation benefits from structure, but suffers from required structure. Make it easy for people to write something (anything!) and worry later about getting it into a structured format.

On a related note, I had a good conversation last night with Alex Russell, a developer on JotSpot (whose apt. we fled to from the tag tuesday tsunami scare – I’m told it wasn’t his apartment. I assumed it was, since he new the WEP key. :-)). One of the interesting things they’re doing is creating wiki software that can be shaped into a more structured application. This bottom-up/content-first-structure-later approach could be very fruitful for technical documentation. He and I both agree that it is difficult to figure out exactly what the structure of your data should be until the data is large enough to cause you pain. Unfortunately, few tools are capable with dealing with this workflow style.

The tools must improve.

This entry was posted on Wednesday, June 15th, 2005 at 10:59 am.