I want to improve my programming skills by studying famous open source projects, but I find it is easy to get lost by just jumping into their source code.

So I decided to read their documentation about their design or architecture (such as UML diagrams) to get a general idea about their code's organization first. To my surprise, however, I can't find any architectural documentation for large open source projects such as Hibernate, Spring, ASP.NET MVC, Rails, etc.

So I've started to wonder: How can an open source project can be successful if new-comer developers have no architectural/design documentation to read, or if the project manager just opened the source code but closed its documentation?

  • 3
    "most"? Can you back this up with concrete statistics? How many did you read? How many are there? How many lacked appropriate documentation? If you don't have numbers, please remove words like "most" and replace them with real facts based on what you really found. Also, please capitalize "I" when referring to yourself. – S.Lott Jun 29 '11 at 10:13
  • @S.Lott Sorry for the subjective "most". I am a newbie in software industry. I do trying to search for documents which I had heard of during college school(such as UML Diagram,Flow Chart,Brief Design Doc,Detaled Design Doc,etc) for the mentioned projects both at their project website or code repository but without luck,only to find some user-guide doc. Can you please teach me some common way to search their desgin/archiecture documents? – TomCaps Jun 29 '11 at 10:32
  • 1
    Please remove "Many". That's just as incorrect as most. please update the question to specifically list the specific open source projects that specifically lack the specific documentation you want to see. Please be precise and specific. Please do not be subjective and vague. – S.Lott Jun 29 '11 at 13:16
  • I suspect that the reason ASP.NET MVC doesn't include UML diagrams is because Visual Studio can create them from the source code. – user16764 Jun 29 '11 at 13:54
  • 4
    You're operating under the false assumption that "enterprisy" is a good thing. What you learned in college about design is all lies: UML has absolutely no value. When creating a project, all you need is a general idea of what it should do and a willingness to throw it away if you do it wrong the first time. For an existing project, just skimming the main header is usually enough to get a good idea about the project layout. – o11c Aug 26 '14 at 6:12
up vote 10 down vote accepted

why an open source project can become successful if new-comer developer have no architectural/design document to read?

The assumption is invariably made that you know what you're doing and have a reasonably intimate understanding of what you're going (and expecting) to see.

If you look into the PHP code of the Symfony framework, for instance, you're expected to already know about dependency injection, events, the model/view/controller pattern, and so forth.

Likewise, if you dive into the C code of the linux kernel, the assumption is that you'll be realistically competent in modularity, signals, processes, threads and what not. You're also expected to have a knack to eat hexadecimal all day and excavate through core dumps with a giant shovel.

The maintainers won't go through the trouble of documenting the architecture because it's matter-of-factly stuff. On occasion, you'll find an outline of what lies where in the source tree. More typically though, the way the source tree is organized makes things self-explanatory.

In short, if you lack any of the skills that the maintainers will expect you know by the time you peek into their code, you're probably digging through stuff that is widely above your pay grade. Familiarize yourself with the concepts first - What is the MVC model? What is dependency injection? Etc. Then dive.

  • 1
    Though if you look at mailing lists the Linux kernel has extensive discussion about the architecture whenever somebody has a problem or wishes to change something. There are also quite a few documents written about it -- though not in the kernel source tree itself. – edA-qa mort-ora-y Jun 29 '11 at 13:33

Most successful open source projects became successful because first and foremost, the program was impressive or did something no other program could do at the time. That doesn't necessarily mean the source is well-documented, since the programmers which began the project to begin with know the code well enough to not need it. It's an unfortunate reality that open source projects don't have to be well-documented. It either has to be a good program or be a mediocre program but well-documented for programmers to express interest in it.

  • In my company,it is a requirement procedure that developers must provide a Detailed Design Document before being approved write any code on a project. Is this procedure abnormal for open source project? – TomCaps Jun 29 '11 at 10:12
  • 5
    @TomCaps I think the biggest reason that so few FOSS projects have extensive documentation is quite simple: if your writing a little program to solve a need that you have, it's likely that since your the developer that you don't also need documentation, you are going to want to spend your time improving the program rather than writing documentation that isn't guaranteed to even be useful to anyone (what if the project is never used by anyone except the developer?). It's not best practice, but many FOSS projects are short on developer-time. – Jeff Welling Jun 29 '11 at 11:48
  • 4
    @TomCaps: This procedure is abnormal for most companies that I know... – Treb Jun 29 '11 at 12:36
  • 1
    Most open source projects are not companies. You are thinking what happens when there is a project I am being paid to build, with a deadline and a budget. If you have a bunch of people coding to fill a need they have or for fun and there is no budget or client you don't have those kinds of things. – Elin Aug 26 '14 at 0:49
  • 1
    @TomCaps -- anyone writing Open Source software can do exactly what they like. Some projects (e.g. the Apache family) have rules and guidelines for anyone commiting code and sometimes this includes doumentation standards etc. Also I would question the value of a "detail design document" as this will invariably lock you into a physical design which (in my personal experience) is usually sub-optimal. A detailed description of "what" the program is supposed to do leaves the developer free to optimize the implementation and apply creative strategies to the solution. – James Anderson Aug 26 '14 at 4:20

Because open source developers are usually talented and also choose project in their expertise area, they already have "documentation" within their skulls. With little exaggeration thorough documentation is needed only if you lack any of those :o)

To be honest, I don't really read "documentation" when facing unknown codebase. A quick introduction, maybe a few conceptual sketches and straight into the code! Experiment, try small changes. Works perfectly for well designed code. If I face horrible mess, then best way to learn them is to refactor bit by bit to improve clarity (ideally with help of unit-testing).

Additional reason could be plain organic design roots of these projects. Architecture is then rather evolved vision in the minds of developers than stated "documented" entity.

The reason such docs often dont exist is pretty simple: Programmers like to program, not write documentation. Especially with open source projects, which developers often contribute during their free/leisure time.

Basically, writing documentation is no fun. And if they arent getting paid for it, who wants to spend their free time doing something thats no fun?

  • Some large open source projects (GCC, the Linux kernel, Firefox, Qt, ....) have most (or a significant portion) of their contributors paid to work (full time or half time) on the project. So even when paid for free software, they don't write a lot of documentation – Basile Starynkevitch Dec 16 '15 at 8:44

protected by gnat Jul 5 '15 at 9:46

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.