Every project we seem to find ourselves documenting with a new fangled approach. We've been searching for that Dharmic principle on documentation that will make the pain go away. So far it has eluded us.
One of the central issues is finding a tool or tools that can be used across the team, in a progressive fashion that lets us coalesce project documentation as we go, as opposed to making it the "bamboo shoots under the fingernails" task at the end of the term sheet.
Code commenting and auto-documenting tools based on components is something we have a relatively good handle on. For example, the FarCry CMS Component API uses Spike Milligan's CFCDOC tool. Plus there are other tools that provide similar JavaDoc style outputs.
No... the real difficulty is trying to find something to build that documentation that ties everything together -- your classic technical specification or user manual.
I've always been intrigued by the RoboHelp offering from Macromedia (formally of eHelp) and have wanted to get my teeth stuck in for a while now. Certainly if its anywhere near as good as Captivate (nee RoboDemo) it would be a winner. But as you might expect, the system is fairly complex and the commitment much more than simply buying the software -- so naturally we're cautious.
I really liked the recent release of documentation for ColdFusion 7, Flash and Breeze but I was surprised to see that Macromedia is not eating their own dog food here. In fact Macromedia uses a totally different product for online documentation: WebWorks from Quadralay Corporation
Is this a legacy of the way things have been done historically (ie. pre-acquisition of eHelp)? Or is this an admission by these documentation teams that RoboHelp does not quite meet their requirements, at least for online documentation?
Posted by modius at 11:23 AM | Permalink