why api documentation is good but not enough

accurately and thoroughly documenting our application programmer interfaces is absolutely critical to making the work we do in libraries and other components useful to other developers (including those who will take over for us in the future). however, as important as api docs are, it isn't enough.

api documentation is like labelling each piece of a larger machine: each screw, bolt, assembly tool, pipe, driveshaft, etc... one may be able to read all of these labels and after examining enough of the other pieces be able to figure out how to assemble the individual bits and pieces into a functioning whole. but one is just as likely not to be able to because there isn't a "big picture" goals provided to work towards and when there are hundreds or thousands of pieces it can be not only time consuming but very mentally taxing to assemble those bits in your head.

this is why we need what i call "high level" documentation: articles that cover in a narrative fashion how to use our technologies. these articles (or tutorials, HOWTOs, whatever you prefer) lead the reader along a path to specific end goals. rather than being comprehensive descriptions of the individual pieces (that's what api docs are for) they help the reader get the bigger picture: the final machine rather than the parts.

this makes the api documentation so much more understandable as the reader will now have a frame of reference to apply to the detailed information. it also makes the api documentation reference material rather than source material for learning, which allows us to write it as such and not try and stuff tutorials into our header files.

and why not put these tutorials in the api documentation? after all, we do have the ability to include mainpage.dox files and general sections in headers. the reason is quite simple: it's not easy to do things like provide references to images or other media from these pages, they aren't community editable (which means, in my experience, that they become static documents and bit rot faster than they should) and there are simply some topics which don't belong in any header file.

for instance, the intro to d-bus article i added today: which header file in kdelibs should that go in? or how about information that ties together multiple disparate technologies? this means that at least some of our high level documentation will live in one place, such as the developer wiki, and some of it will be in our api documentation.

spreading our information around like that simply makes it harder than necessary for those researching kde technology to get all their information. the obvious answer is to keep it all in one, community editable place.

and so i make the case that api documentation is vital and critical, that it needs to be augmented with high level tutorials and that the high level documentation should all be placed on the developer wiki. if you are providing a key and/or useful technology for kde4 and you haven't thought about providing this high level documentation, should the project really be shipping that work? personally i don't think so. just as we have complete api documentation coverage as a goal and requirement for public api's, i believe we should have high level documentation for all libraries/technologies in kde as a goal for the kde4 series.

and that is precisely what the developer wiki is attempting to provide. please, do your part in this effort. i know i've been harping on about this for the last few months, but i'm a pain like that: i'll keep on about it until someone either shows me that it isn't needed or until the developer wiki is full of nice articles on the pillars of kde4 from a developer's point of view.

ok, rant over. discuss. =)