How can open source projects be successful without documentation about their design or architecture?

Question

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?

Answer 1

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.

Answer 2

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.

Answer 3

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.

Answer 4

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?