General discussion


Open Source Documentation Weaknesses

By hramsdell ·
Over the years it seems like there have been many articles about the bane of open source development being the limited documentation. Is this still the case? I've been having a hard time finding quality documentation for many systems.

So I somewhat took the developer mentallity and decided to do it myself. The company I work for has recently started documenting in extensive detail open source systems including Azureus, Eclipse, JUnit, JBoss, and hundreds of others. We are looking for feedback and suggestions on the types of diagrams, models, metrics, etc. that would be useful to you all as developers of this system. Currently we include a number of software engineering methodologies include UML, MDA, OOA/OOD, SSADM. There is also complexity indexes and details of unused/dead code. Please take a look and give us some honest feedback.

If anyone would be so kind as to help get the word out. We'd love to open up the flood gates for more organizations to use open source software.


Howard Ramsdell
Software Engineer
The Software Revolution Inc.

This conversation is currently closed to new comments.

Thread display: Collapse - | Expand +

All Comments

Collapse -

it is to bad

by Jaqui In reply to Open Source Documentation ...

you picked a PROPRIETARY language to document software in.

until SUN releases the sources of THEIR jvm / jree, Java is proprietary.
besides being criminally bloated and a violation of the GNU-GPL v3 if included with an open source operating system under the GNU-GPL.

Collapse -

Thanks for the response!

by hramsdell In reply to it is to bad

Do you have a suggestion for the language we should document next? We are currently working on ADA, COBOL, MUMPS and C automated documentation. These should be ready in the next week or two.

Collapse -


by Neon Samurai In reply to Thanks for the response!

I should probably stay in the lurking mode until I'm sure I understand the question but wouldn't Tex or HTML be a good documenting language? Assuming your not going to to with text (guess it kills the pictures if text only).

Collapse -

Actually, I have a suggestion

by Jaqui In reply to Thanks for the response!

pick applications with poor documentation and make good documentation for them.

write the missing app manuals.

fix documentation that is obscure, make it easier for the typical and user to have something to help them USE the open source applications.

The Linux Documentation Project [ ] tried doing exactly that. While they have a great collection of documentation, it is mostly not written for end users.

The lack of good app manuals is often the biggest drawback for open source software.

Collapse -

I agree

by hramsdell In reply to Actually, I have a sugges ...

I actually agree with this assessment. I think is trying to fill this void through a wiki approach. So the market for user documentation already exsists to a lesser extent. The problem with doing user documentation is that typically the person doing it should atleast be knowledgeable about the use of each of the products, not always an easy task.

Instead the approach taken here is more geared towards the actual developers of open source systems. Since there are generally large numbers of changes being made at any given time by potentially hundreds of developers, it's easy to understand why vaste amounts of dead code or just inefficient code exists in the open source systems. Not to mention the problems with trying to get government and major corporate entities to adopt the programs.

If you are a developer or a technical end user who needs to understand the nitty gritty check out the project at:

You can sign into the full documentation using:

username - guest
password - guest


Related Discussions

Related Forums