How to manage end user documentation for a project under continuous integration?

Question

I have a project under continuous integration and would like to add end user documentation to the project. The end user documentation is a user manual, not API documentation. In our environment we use windows, c#, msbuild, cruisecontrol.net and subversion. We are currently using DocToHelp to create our help file, which is based on an msword document.

I'm looking for some guidance on how to manage the end user documentation. What documentation tools should I use? Should any of the documentation tools be part of the build script? Should the output files from the documentation tool be stored in subversion? What type of help files would be best to use?

Answer 1

We has been using XMLMind XML Editor to produce user documentation in the unified docbook format that can be stored in a version control system for the past 6 years. We use standard XSL transformations to generate user documentation from docbook in HTML and PDF format. Of course, this all is a part of the Continuous Integration and release build cycle.

Hope this helps.

Answer 2

You might want to take a look at Doxygen: http://www.stack.nl/~dimitri/doxygen/

Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#

Answer 3

I don't know DocToHelp but here is my take:

Even if it's the only thing you do: Start with adding your generated help file and all the files you used to create it in your version control system.

If generating the help file is not much more then processing a Word doc file then perhaps I wouldn't bother integrating it on the CI server. Your CI server's build artifact folder will just contain the help file as fetched from version control.

If there is a whole bunch of files (perhaps externally linked images in the doc?) and there is a chance of failure you could add it (if the help file building tool allows).

Basically what your CI server would prove then is if it can reproduce your help file from version control (did you commit and add everything?). Taking it even further you could build automated tests which would examine the build help file and compare it with the referenced helpcontext IDs in the software itself. But here I am speculating (I haven't done helpfiles in ages :-)).