Opinions on documentation

I think that putting the tutorial and reference on a wiki is a commendable idea for the following reasons

I mantain the Smarty tutorial which is in DocBook format and here's what I think

• There is a steep learning curve in understanding the tags
• Identifying a piece of text amongst lots of files
• Small typo's in the markup will make the compile fail miserably
• Integrating images can only be done with patience
• Linking to external web sites involves creating that external site as an entity. Simple on the fly external web references are therefor impossible
• It can only really be updated via CVS/SVN in a collab enviroment
• Manuals are "built" but can often be out of date as soon as they are released
• A manual has to be "compiled" before even minor changed can be viewed - and that includes getting the compile enviroment up and running
• However it does output the text in pdf, html et all formats

The advantages of a Wiki are

• A document can be corrected or ammended on the fly
• A new page to highlight a feature is easily done
• its easy to add images or media
• its easy to reference extenral sites
• Syntax is familiar, wuick and easy
• Users have their own space to share thoughts and create mockups, drafts etc
• It will always be current

As a little side note on user experience, we all know that developing an application is only one half of a project, the other is the documentation. I have now got in the habit of creating a Wiki right at the start and generally it goes like this (for a web application for example)

• The brief is tapped into the Wiki with the client. Indeed the client is encouraged go an modify and discuss with end users to get an accurate brief
• A to do list/ Menu is generated, with a set of objectives/targets
• As the applicaiton is developed, manuals for sections just coded are entered into the Wiki manual
• End users test the applications and give their feedback, feature requests etc in the comments section of each page
• These comments can be enacted upon with minor tweaks to code and manual
• Users end up putting tips and trick in themselves, whereupon the applcation is documented and by the End users - thats what I call heaven
• The developer can watch the wiki and see end user problems and implement them in code