Slashdot Mirror
Open Source Tools For Documentation Creation?
"I've found some tools I could use, but they all live on That Other System. The place I'm doing this for is open to considering Open Source tools for the project, so I have a chance to throw a couple of more chinks into the IS ivory tower armor if I can find find the right tools.
So I'd love some feedback from the group mind: what tools do you use to help keep a handle on large project designs, especially those involving database systems. I need process flow documentation and a way to manage the database definitions, but I'd love to hear about all of your favorite tools. I'd love to be able to bring forward a complete project management solution that's open source, just to prove it can be done to the people who believe life begins and ends with three letters and white coats...."
This technology was hot for a while, and eventually fizzled out for the usual one-size-doesn't-fit-all reasons, but there are a couple of features in it that I like:
1. Cross-referenced data elements and pseudocode. This means that any time you build a statement like "put tab A in slot B" then tab A and slot B are already defined in the data model. In fact just about all the nouns and relationships (eg "find all where is ") should be pickable from the data model (the items in above should all be such). Even the types of local variables should be pickable from the model.
2. In keeping with the above, you need a rich data model. That means you have to give relationships names and correct cardinalities, and put in things like delete rules for foreign keys. Too many times I see "data modellers" slap together a few entities with unnamed lines for the relationships, and then end up with a denormalized mess because no one could figure out what the relationships mean. Incorrect or misunderstood relationships are where most bugs come from. Keeping the data model up-to-date can be a real pain, but the alternative is chaos.
---- "If we have to go on with these damned quantum jumps, then I'm sorry that I ever got involved" - Erwin Schrodinger
Apart from the name, this is the best tool I found for C++ / IDL / C. Better than Javadoc!
www.doxygen.org
I am not a number! I am a man! And don't you
Apple released a program called HeaderDoc under the APSL (now 20% friendlier!), written in Perl:
"HeaderDoc is a tool for generating HTML reference documentation from comments in C or C++ header files. It is written in Perl for easy portability. Similar to JavaDoc, it allows developers to easily document their interfaces and export that information into HTML."
Realistically, I'm not sure if this helps your cause, but I hope it does!
Look at the Toolkit for Conceptual Modeling It runs under Linux and Solaris and is distributed under the GPL. It can be used to design tables, trees, ER diagrams, UML(use cases, collaboration diagrams, etc.), data and event flow diagrams, state transition diagrams, and many other types of documents. It can output data in PostScript, encapsulated PostScript, or FIG. I've used it for projects before and it offers pretty much all of the functionality you would get from a program like Visio. (And if you drop the TCM diagrams into LaTeX, you'll get something that looks better than anything you could hope to produce on "that other platform".)
Good luck!
When violence rules the world outside / And the headlines make me want to cry / It's not the time to just keep quiet
Done by one of the Berlin programmers.
-- Eat your greens or I'll hit you!
-- Eat your greens or I'll hit you!