One of my primary requirement tools is Macromedia’s RoboHelp. RoboHelp is best known for creating help systems and documentation and has great features such as the ability to separate information into individual topics, tie the topics to an independent table of contents, and then publish the results to multiple formats. However, RoboHelp has some serious drawbacks once the initial document has been completed.
My product design documents, average 300-500 pages for a medium sized Business Process Management project. The document includes process models, user interfaces (requirements and mock-ups), system interfaces, alerts, events, etc. For each process step, I create a RoboHelp topic page that contains the Description, Requirements, Unit Test Script, and associated page Help text. I then build a relevant table of contents and publish using the webhelp format (see image)
and to Microsoft Word. The web format is used as a quick reference guide and Microsoft Word format is used during face-to-face review sessions and official delivery. Almost all my contracts specify delivery of documentation in Microsoft Word. MediaWiki topics and web-enabled the table of contents to duplicate the Webhelp navigation.
The downside of RoboHelp is change management and collaboration. Clarifications, re-engineering, and other changes can occur every time the document is opened, especially when you have 100+ user interfaces, 20-30 system interfaces, and a dozen or so processes and sub-processes. There is no better method to capture changes then to have a pen and the printed document. While updating RoboHelp topics are quite easy, viewing changes can really only be accomplished in Microsoft Word via a document compare redlining of the prior version. This is a bit taxing for the initial document delivery, but completely unworkable during the software design and construction phase of the project. The project team grows exponentially and many small changes and clarifications are realized. Capturing the information simple and republishing documentation is a nightmare. Even more of a nightmare, is the need to license RoboHelp for each user. There is no way I would ask my clients to provide RoboHelp licenses to the whole project team or ask engineers and developers to learn this application just to keep the documentation up to date.
Of course, if you can work in a full web environment Wikis are the near-perfect collaboration tool. Easy enough to use so engineers and developers are not burdened when entering notes and comments, plus providing history, redlining capabilities, recent changes and related links functionality.
For my current project, I converted the RoboHelp topics to
Added benefits included image history capabilities and the RSS feeds on the recent changes page. I have subscribed to the RSS feed via my NewsGator RSS reader and can quickly review all changes as they occur. With respect to image history, we use a simply 4 digit file naming protocol (1234.jpg) for the User Interfaces. For each design iteration we simple upload a new User Interface snapshot using the same filename, overwriting the old image. When viewing the history, we can cycle through each mock-up while reviewing the requirements changes. Very powerful when trying to recall why you made changes a month later. We do the same steps for the process models.