Why documentation matters

If you kept an eye on Planet-PHP during the past days, you will have seen a discussion emerging about the sense of doc blocks and documentation in general. Travis Swicegood states a quite interessting point of view. His main point is, that program languages themselves are declarative and that it is somewhat stupid to describe the purpose of a method in plain english, if it has been already described by the programming language itself. Although I never thought in this direction so far, I can see a valid point here. Partly.

I basically agree with Travis, that programming languages are declarative and (for the usual case) you shouldn't need much documentation for a class, if you name your methods and attributes properly. At least for an experienced programmer, the names should be obvious in most cases. But at least in PHP we have some major issues, which are modelled in code and are not obvious from the outside:

The most obvious thing are exceptions. Unlike Java, PHP does not require that an exception is either caught or the method is declared to throw it again. If you are going to use a programming libraray, you therefore have no possibility to see, which method throws which exceptions, without proper documentation. Another point are read/write only properties. Since PHP does not have a modifier for this so far, you need to go the way of interceptors. Properties which are "declared" using overloading are not as obvious as real attributes are, because they simply are not a declarative construct of the language itself. You therefore need documentation here to mark those up for the user.

But even if you neither use exceptions, nor interceptors to define properties, you still have a lot of cases, where pure naming is not sufficient to make a foreign user see in 1 glance, what happens. Simple things like the classes that are used in realtion with another class are often not obvious. Just think in matters of the factory pattern, dependency injection and similar. Additionally, if you only have the code itself, navigation is quite hard, if you have a large code base. Browsing directory structures to look for what you are searching is not fun, especially, if concepts are used, that you are not familiar with, yet.

Another (and propably the most important) point is simply the difference between people. I'm doing PHP for over 6 years now, I've dealt with a lot of libraries in PHP and have developed many applications. I'm heavily affected by what I've done and I've been inspired by a lot of people and experiences. But you are different! Are you sure, that my thoughts are as obvious to you as they are to me? No, you never can asure that. And that's a major point, why I will have to explain my thoughts to you in a more complex syntax than PHP to make you understand the overall concept behind my doings. This is quite natural and will not change any time soon, because even if programming languages are declarative, they only hava a very limited syntax. Surely you can describe all that in a programming language, too (you do! what else is your complete code base than your concepts and thoughts written down?). But to understand it all, you would need to read the complete code and not only the prototypes.

I think I made my point quite clear so far. But Travis still has a valid point. Inline API docs are not, what he is looking for in the matters of "documentation". I agree with him. No, I'm not contradictory, but in the matter of my last paragraph, people are simply different. While I consider inline API documentation an important part of any code, because it simply gives me an overall reference of what is available, I don't look at in the first glance.

While thinking about Travis matters, I analyzed my own way of working with documentation. When I start with something new (a new library for example), the first thing I want to know is "How does this work in general?". I'm sure a lot of developers have the same feeling and don't want to dig into API docs for hours and hours, before they have the big picture and understand the overall concept.

So, what is basically needed to get started is a tutorial. I consider tutorials the most important part of any documentation. A simple step by step introduction to a practical usage example gives you more than 1000 lines of inline docs when getting started with something new, because you gather the main points you are interessted in with very few learning effort:

• What is this?

• What can I do with it?

• What is the overall concept behind it?

• How am I expected to use it?

These 4 questions reflect the main information I typically want to have when digging into something new and I actually cannot imagine anything that can help me better than a tutorial here.

Ok, after reading the tutorial for a specific component, what comes next? The next step is to actually face the problem I want to solve using the library. Yes, that is basically what I want to do, solving a problem. I usually start copying some code from the tutorial, which I consider valid for the solution of my problem. Now I have to adjust that piece of code to suite my needs and make it do, what I actually want it to do. At this point API documentation enters the game. What I need is a reference of a specific class or method, to see with 1 glimpse, what I can do to adjust the behaviour. The most important questions now are:

• What are the options of an object and how do they affect the objects behaviour?

• What are the parameters of a method and how do they affect the behaviour of the method?

• What are related classes and methods, which could propably solve my problem easier or in a better way?

• Which side effects will I have to expect, if I use this class / method?

While the first 2 points should mostly be covered by the code itself (you know, programming languages are declarative), the latter 2 are mostly not. They show another 2 important points of API documentation: The relation between classes/methods and some portions of the background information, that is usually hidden somewhat deep inside the code.

So far so good, I managed to realize what I wanted to achieve. If I reached this point with reasonable time effort, the documentation of the project seems not that bad, does it? What comes next? I propably will not use the same classes I just used very soon again. But the time will come, when I come back for one of 2 reasons:

• The code I've writen needs maintainance

• I need to solve a similar problem and want to use the library again

What is different now in contrast to the first time I needed the documentation? I already have the big picture of the component in mind. I also have some working code at hands, which was written by myself and should therefore be understandable for me (inline docs help! ;). The tutorial might be helpfull now, to recall some facts. But more important are the API docs now, again.

So, why am I telling you all this? Basically to show you my view on the documentation issue. I agree with the fact, that API docs are not the solution to all of your problems. A well written tutorial helps much more in the first steps, than any API docs can do. And I think that is basically the same point Travis mentions, when he says "Give me a unit test any day over a three paragraph docblock". Exploring new terrain by example is much more effective than digging into pages of API description. But that does not mean, API docs are useless. They are very important for the further steps and should solve the issue of the limited declarativity a programming language has, due to its limited syntax.

Finally I'd like to refer to the documentation of eZ Components. I think we manage very good to provide all of the named. For each component we have different documentation forms online. A tutorial for the main functionality of a component exists (for example the ConsoleTools tutorial). Beside that, we have additional code examples shipped with each components source, for people that prefer reading PHP over English. ;) The complete source of eZ Components is inline documented and the documentation is rendered online (e.g. ConsoleTools). The API docs are enhanced by a lot of usefull features, like a special markup for the most important classes and some example code in the class docs of. Also quite nice in my eyes is the linking between tutorials and API docs, which helps you to get detailed information about a specific class or method right from the tutorial with 1 click. Finally, especially important for Travis ;), eZ Components are fully unit tested.

Is there anything more you would expect? Tell me, I'm currious! :)