[plug] project documentation software in use?

Denis Brown dsbrown at cyllene.uwa.edu.au
Fri Dec 5 11:54:07 WST 2003


Dear PLUG list members,

I've done some Googling and come up with a few alternatives but I'd like to 
ask if anyone here is using open source software to produce systems 
documentation.

I am embarking on a fairly major project involving several sites, 
client-server, local high-speed networks to connect the graphical 
workstations to the servers, links to the university LAN and beyond, etc, 
etc.   I want to document the project every step of the way so that if I 
fall under a bus, retire, win Lotto (yay!) or whatever, others can take up 
the reigns and fully understand QUICKLY how the system hangs together, what 
is required on the server, each workstation, etc, etc.   I want to include 
detail down to server and workstation configuration, BIOS level, MAC 
address, where we purchased it, how much, purchase order number... all that 
fruit, as well as the highest "the knee bone connects to the thigh bone" 
level.   Ideally I'd like to incorporate maintenance details as well - when 
the air conditioning filters need to be cleaned/changed, for example.

I started with the concept of a Mind Map, where the central idea and major 
supporting themes are represented.  Then at each stage further out, the 
themes are themselves fleshed out.   That provides a good overview and 
allows for the various interactions to be explored.   Ideal task for any 
hyperlinking architecture, I guess.   I also looked at things like Dia for 
the production of detail-level diagrammes.   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.

One thought I had was to employ an ontology which records the metadata and 
data in a semi-graphical form - project from Stanford Uni.   Ontology 
implementation would allow remote access to the "database" of ideas and 
notes.   They use XML in their implementation.   ProManager on the other 
hand uses PHP and an SQL database (eg. PostgreSQL, MySQL) and I'm a bit 
more attracted to that, truth be told, from an "I know this stuff" 
perspective.   I saw a reference from somebody complaining about Dia in 
that it died and nuked the nice diagrammes they'd been working on 
:-(   Then there's TCM from a university in Amsterdam, which provides a lot 
of tools for various graphical tasks but it seems they are not that well 
tied together, at least on a first reading.

So, TIA!
Denis





More information about the plug mailing list