open source project with real design documentation [closed]

Question

You can find many open source projects in the INTERNET (such as Linux,open office,...)

But i did not find any open source project with a complete ,good and REAL documentation.

I don't mean just source documentation. I mean, gathering costumer requirements, design patterns , and all paperworks.

Kind regards

Answer 1

Why do we have requirements documents and design documents? To hammer out an agreement between two parties, one who wants certain software, and another who is charged with making it. The document is useful because it helps the two parties work together to make the right software efficiently.

Sometimes in open source software you can find that kind of relationship. And in such cases, you can sometimes find up-front design documents. If you want to add a feature to the Python programming language, you must write a Python Enhancement Proposal and get it approved, to ensure that what you're implementing is something the Python maintainers are willing to take. You can find many links to design documents in this page of OpenSolaris documentation; I'm guessing the "customer" here is Sun marketing. I recently designed an API for some open source software that someone else implemented, and I wrote a specification for that up front.

But a lot of open source development follows a totally different model, where one or more of the following factors apply:

• The unit of work is a single feature or bug fix. Often in a bug tracking system you can find one-paragraph requirements documents, if you want to think of them that way. Smaller units of work are actually a big advantage; closed source development often can't follow such a model because the transaction costs (of establishing trust, figuring out what is needed, agreeing on scope and price, etc.) are too high.

• The developers are working on software for themselves. If you know what you want, writing a formal design document might not pay off. (You might write a few squiggles on a whiteboard instead.)

• The project isn't initially intended to see widespread use. If the code is going to be running and doing its job on your machine in an hour, how would a separate design document help? If it grows over time into something other people can use, at what point should process documentation have entered the picture?

• There was a design document but it wasn't published. Remember, the purpose of these documents is to help make the right software efficiently. Once it's made, the documents are not terribly useful. (Also: open source software is often written under contract for a company. While the finished code is public, the process documentation may be explicitly or implicitly considered confidential.)

• The developers just aren't willing to do up-front design. I tend to think this is too bad, but alas, it is a contributing factor.

Sometimes software is documented after it's implemented and proven. Here is a part of the GCC manual describing its internals. Here's one about Mozilla's JavaScript engine. It's fairly easy to find examples if there's a specific project you're interested in. Googling linux kernel design found more free, detailed documentation.

Answer 2

Open Source projects usually start off from an itch to scratch unlike proprietary applications which start off targeting a rich potential customer (customer requirements). Design patterns have nothing to do with documentation. It's just boilerplate design. As for paperwork, you make that sound like a "good thing". :)

There are open source projects which detail design in advance before implementation. A quick one that comes to mind is the bzr DVCS. Docs are available Here. Martin Pool spent quite a while documenting it before he started work.

Answer 3

Take a look at (early versions of) jHotDraw. That is the java version of the HotDraw framework that a.o. Erich Gamma (GoF) developed for his pattern language work.

You are unlikely to find any projects (open or closed source) with complete and up-to-date documentation, including dependency maps. You might be able to find something extremely small build for educational purposes. For systems where this is mandated by law, the actual quality of the documents is usually very low, as they are not produced for any real benefit for the writer or the consumer of the information but just to cover legal responsibility.

In open source projects there is a strong tendency to only write documentation that is directly used, as they have a very good working prioritising process. Communication is needed at a hand-over of work. Documentation can provide that. But in most open source projects, there is a strong tendency for people wanting a feature to also be the implementor of the feature. In that situation there is little need for much documentation. Open source projects need overview documentation describing work standards, design patterns used, and everything that can help new contributors getting up to speed.

If you want to really understand how difficult it is to properly manage dependencies, take a look at:

Managing design data: the five dimensions of CAD frameworks,configuration management, and product data management van den Hamer, P.; Lepoeter, K. Proceedings of the IEEE Volume 84, Issue 1, Jan 1996 Page(s):42 - 56 Digital Object Identifier 10.1109/5.476025