in english

(The estimated reading time for this post is 8 minutes)

When dealing with software you have not written yourself (or have written a year ago which can make it as alien as code someone else wrote) you have to rely on the software”s documentation.

The quality of documentation varies a lot from one project/software to another: Some projects have really good and useful documentation, some just gather links to articles by third parties and some completely lack documentation, the quality of a software”s documentation should always be one of the most important arguments for or against using a certain software.

One of the worst kind of “documentation” is the “API docs”. It”s not useless at all, you need it if you use that on class from the software and you really need to know in detail which methods instances of that class have, but some projects seem to think that it is a replacement for real documentation.

When I had to learn JAVA at university we had to do a so-called “software project” written in JAVA (it was with a group of around 10 people and ran for half a year). Back then JAVA”s documentation was pretty much just their auto-generated “JAVAdoc” API documentation. (They had a few tutorials but those were written so badly that they were of no real use to someone trying to figure out how to do something.)

API docs help when you are in the middle of doing something and you need details about the entities you work with, when you have already picked your entities, but they do not help you when you are looking for something like “I need a container for a bunch of different objects that might or might not have the same type with the following properties…”.

Let”s look at a few project”s documentation and see how good they are:


The Python documentation is separated into different segments: There”s the Tutorial that”s even marked with “Start here” so the beginner knows where to dive in. Then there”s the library reference that explains what a certain built-in module can do and how it works before diving into the details of the classes and functions that module supplies.

The Python docs are very good, it”s easy for a newbie to dive in while still offering people that need info about that one special function a direct and quick access. It”s a good compromise but does lack something that other languages” docs have: User comments that can sometimes elaborate something that the docs don”t make clear enough (you just cannot see any problem that people might have).


PHP”s documentation is not as strictly separated as Python”s, but the document is separated into chapters that somewhat mirror the segments that Python”s docs have. It starts with a tutorial, then goes over the language syntax with then going over the modules that PHP comes with.

PHP is easy to learn but that is also due to the really good docs: You go through the first two chapters of the docs and you know your way around. Then you can look up the special functionality that you need for whatever you do. The biggest plus point of the PHP docs is that every documentation page has a comment section where uses can contribute notes about quirks that a certain function has or that offer some example for common use cases. The md5 documentation for example shows you why your calculated md5 hash might not match one you calculated in .net or mysql. This is really useful not only to new users but also people that do know their way around but stumble on some weird quirk.

All in all PHP might be a badly designed language but the documentation is really good and helps you dive into it quickly and effectively. The user comments are (while there is of course the danger of spam) a very valuable tool to enrich your docs with information that might just not fit into the actual documentation article.

Ruby On Rails

Ruby on Rails”s docs are separated in the API docs, a link to a bunch of books you can buy and a bunch of links to tutorials somewhere on the net.

This is an example for bad documentation: The team just supplies API docs that are not really all that helpful if you don”t know exactly what you are looking for in the first place. Having the second aspect in your docs be advertising for books that are not available for free does make your thingy look like somewhat of a scam, the new users feels like he has to pay a tax to start using your stuff. Not good.

The fact that there are good tutorials on the net is neat and will help users, but what happens when you change something and the linked tutorial doesn”t work anymore? Your users will try to use it and fail and how should they be able to determine which tutorial is right and which ain”t? If they have two tutorials that work but that work somewhat different, how can they determine which can be considered “best practice”?

All in all the Ruby On Rails documentation is not good, while the framework might be opinionated (something I always like) it lacks tutorials by the devs that the user can be sure are correct and teaching best practices.


Django”s documentation is separated into a few main parts: The essential docs that include installation howtos, the tutorial working you through creating an application with django and and the FAQ. The next segment called “Reference” is going into detail about the different parts of django and how to work with them. The docs end with a howto on deployment and a few howtos for common problems.

The best thing about the django docs is the style. It”s not weird technobabble or random API docs: It”s written in plain English with a clear focus on the audience. The template language documentation for example is separated in the part for “HTML authors” and the part for “Python Programmers“, with the first part being completely read- and understandable by someone with no clue about python or django (like someone who”s just a designer that builds the HTML for a django application) and the latter one telling you how to do powerful thingy by extending the built-in stuff.

All in all Django”s docs lack the comment feature that PHP has but probably have the best writing style and are the easiest to work with and understand.

All documentation I reviewed here is for rather popular projects and it”s already obvious how different the quality in those big projects is, when you come to even smaller projects the quality can diverge even more.

Some big projects I didn”t have to review in detail (like JAVA”s docs that are pretty much still a trainwreck) but what you always have to keep in mind: A software with bad documentation that does not empower you will require you to buy books where someone explains what all the fuss is about. But usually there”s not “the one” book, look at how many JAVA books there are (JAVA is just one example, C, C++, C# ain”t much better)! With so many books around you”ll have to dig through book recommendations to see which one of the books is worth reading and which might help you, which is even more time you have to invest into something plus the books usually ain”t free.

When you decide on the software you want to use for your next project, have a look at the documentation for the project. Read through it so see if you feel like it”s really telling you how it works. If there are books available that is a plus (see, I don”t hate books! ;-) ), but you shouldn”t be forced to buy books just to be able to use something; books should provide something different that the official docs, like the O”Reilly “cookbooks” that offer recipes for common problems for example. A book can also wrap the documentation up in a different way which can help you understand them better.

Do you know other projects that have a particularly good or bad documentation? Please share them in the comments.