[plug] project documentation software in use?

[Derek Fountain]

> What I would value is some 
> feedback on what people are using themselves, or have seen in use and have 
> been impressed with in the field.

When I was working for IBM they had a 1000+ page Framemaker document which 
described the complete test plan for a product. There was a whole lot of 
information about the product, what it was supposed to do, what general error 
conditions there were, etc. There was then several hundred pages describing 
tests - each test detailed the environment, hardware, software, procedures 
and expected results, plus other hard-to-pin-down stuff like what the test 
actually stressed and what it proved if it worked.

Three of us designed a complete data repository for this information. The bulk 
of the test plan was written in XML with several XSLT style sheets used to 
translate it into some readable format depending on who was asking (PDF for 
the managers, HTML for the testers, bullet points for the test designers, 
etc.). Since the test format was machine readable, automating parts of a test 
(like configuring a machine with the right software versions, etc.) was 
easy(ish). All this worked very well - even with hindsight, XML was the 
perfect solution. :o)

With your example, some stuff immediately lends itself to XML: machines, 
configurations, versions, purchase details and so on. XML is also good at 
pointers and cross references, which can be used for this sort of thing:

<bone type="knee" id="leftkneebone">
  <connection side="top" xref="leftthighbone" />
  <connection side="bottom" xref="leftshinbone" />
</bone>

XML also suits your "Mind Map" ideas - a hierarchical system with more details 
(in the form of attributes, elements, references, etc.) added as required.

As it turned out, I used Dia myself for diagrams in the IBM project. I never 
had any problem with it, although it wasn't full featured enough for what I 
wanted. It felt like a work in progress. We actually switched to SVG format. 
SVG is an XML application, so it all fit together quite nicely - embedding 
images and diagrams was a piece of cake, and the PDF etc. converters all 
understood SVG.

We did a lot of research back then trying to find something suitable, and 
there wasn't anything for the job we wanted doing. IBM was in a position to 
pay 3 of us to custom build an XML/XSLT solution, and it worked really well. 
I bet if you do find an off-the-shelf package to solve your problem, it'll be 
XML based!

For what it's worth.... :o)

-- 
> eatapple
core dump