Daemonite: Documentation tools and other cosmic forces Archive

Daemonite: Documentation tools and other cosmic forces Archive


Monday, March 14, 2005
Documentation tools and other cosmic forces

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
Trackback: http://blog.daemon.com.au/cgi-bin/dmblog/mt-tb.cgi/272

Comments

Been a while since I looked at robohelp so I'm not sure how useful it is at the moment. We currently use Apache Forrest for technical documentation as it allows documentation to be written in simple XML (from within CFEclipse as we develop) it then generates online documentation (and PDF) and I believe its used by Apache for their online documentation. An alternative product I plan to look at is confluence, its by Jira guys - Atlassian.

Posted by: Kola Oyedeji on March 14, 2005 09:36 PM

You can also try Vex
http://vex.sourceforge.net/

I think that does docbook stuff - I haven't really tried it

Posted by: rob on March 15, 2005 08:12 AM