Tuesday, November 10, 2009


We got excellent documentation!



Ever try to work with a library you've never dealt with before? How do you approach the task? Do you try to find another program which uses the library and cannibalize it? Get someone who already knows how to use it to teach you? Find a good example? Or just trudge your way through and get something that barely works?

I personally would like to have some good documentation which tells me exactly what I need to do to get the job done. Something which I can rely on to tell me everything I need to know, and to avoid any particular pitfalls.

Except most of the time documentation is written by people who would be better off in some other profession. Like terrorist interrogators. Or perhaps the Spanish Inquisition.

Although when you talk to people about the documentation for their library, they act like the documentation is two stone tablets brought down from heaven with sacred commandments written on them. Perhaps it is. But in the same fashion, the documentation is just as mysterious to anyone who hasn't spent years studying the library to decipher its true meaning.

For many libraries, I have spent hours pouring over their documentation, to come up with like 5-10 lines of code to do what I needed to do. 10 hours for 10 lines of code? A bit much I think. Why can't people make documentation for those not familiar with the library, so they can get all the basic tasks done, and provide good reference for anything more advanced? Sometimes the documentation is so completely unhelpful, that I have to resort to the source code, or scour the internet for something to help me. This is completely unacceptable.

Lets look at some of the various types of offenders.


Doxygen equals documentation.

This is the kind of documentation written by those obnoxious programmers who don't want to write any documentation at all. They run a script on their source code which creates a set of HTML pages with a list of all the files in the library, a list of functions and classes, and all nicely interlinked. It also pulls out the comments about each function and clearly displays it. Sure it makes it easy to jump back and forth in a browser between various internals of the source. But it really gives no insight on how to use the library. If the library is written really cleanly, and commented well, perhaps this helps, but usually those creating the library didn't put any more effort into it than they put into creating their documentation.


Really, honest, there's documentation!

Then there are those that try to convince you they have documentation. You have a set of text files, or an HTML file, or a PDF or whatever which tells you how amazing the library is, and tells you all the wonderful things the library is capable of. They'll even give you notable examples of programs using their library. You'll have a great comparison chart of why this library is better than its competitors. You'll even get some design documentation, rational, and tips on how you can expand the library further. Good luck finding a single sentence which actually tells you how to use it.


We got you the bare essentials right over here, or was it over there?

Then you have the documentation which can never give you any complete idea. Sure, just use this function and pass it these six arrays all filled out. Don't worry about what to put in them, those arrays are explained on another page. Oh yeah this array can be used for a trillion different things, depending on which function you use it with, so we'll just enumerate what you may want to use it for. You may get more information looking at these data types though. Before you know it, you're looking at 20 different pages trying to figure out how to bring together the information to use a single function.

I see your warrant, and I raise you a lawyer!

This kind of documentation seems to be written by those that don't actually want you to use their library and are all evasive about it. Every time you think the documentation is going to comply and actually tell you something useful, you're faced with something that isn't what you wanted. You'll get a bunch of small 4 line examples, each that do something, but no explanation as to what they're doing exactly. You'll even be told here and there some cryptic details about what a function supposedly does. Good luck figuring how to use anything.

I see your lawyer, and I'll bury you with an army of lawyers!

This is one of the worst offenders that big companies or organizations generally pull. You'll get "complete working examples", and a lot of it. The examples will be thousands of lines long and perform a million other things besides what the library itself does, let alone the function you just looked up. Good luck finding what you need amidst all the noise. The Dietel & Dietel line of how to program books that many colleges and universities use play the same game. Create enough information overload in the simplest of cases and force you to switch to a major in marketing.

I'm sorry your honor, I didn't realize I didn't turn over the last chapter.

This kind of documentation isn't so bad. You'll get some good notes on how to do all the basic stuff the library is capable of. But any function or class with any sort of complexity is completely missing, and you'll have to refer to the source code. But I guess the authors don't know how to put the trickier things into words, at least not like the easier stuff.


I think that about sums it up. There are some libraries out there with good documentation, but usually its of the kinds described above. Anyone else feel the same way?

14 comments:

Žygimantas said...

Oh, yes. I especially hate those with dozens of huge examples. I hate reading examples when I do not know how library actually works. Truly, documentation writers MUST be psychologists who knows how human brains adapt the information! Try to find psychologists in developers... :D

McFiredrill said...

Doxygen generated HTML is certainly completely useless in my experience. A list of functions doesn't tell you anything about how to actually use them.

What about man pages? SDL and libcaca come with man pages for each function, much like standard C library man pages. They are clear in their explanations. I'm not sure how these manpages are made.

insane coder said...

While cleaning up spam, I accidentally deleted a comment which asked about manpages.

A lot of system man pages are fairly well written. However, some things make the same mistakes described in this article, especially when it comes to multiple things that need to be used together, or requires domain specific knowledge.

MBBS in Philippines said...

Wisdom Overseasis authorized India's Exclusive Partner of Southwestern University PHINMA, the Philippines established its strong trust in the minds of all the Indian medical aspirants and their parents. Under the excellent leadership of the founder Director Mr. Thummala Ravikanth, Wisdom meritoriously won the hearts of thousands of future doctors and was praised as the “Top Medical Career Growth Specialists" among Overseas Medical Education Consultants in India.

Southwestern University PHINMAglobally recognized university in Cebu City, the Philippines facilitating educational service from 1946. With the sole aim of serving the world by providing an accessible, affordable, and high-quality education to all the local and foreign students. SWU PHINMA is undergoing continuous changes and shaping itself as the best leader with major improvements in academics, technology, and infrastructure also in improving the quality of student life.

Bella spa said...

A popular type of massage, massage near me, involves the use the therapist's entire body to massage the client.

shanjanaarora said...

good spa services hot massage in chennai

izspa.net said...

Firm Support and Rocking: The use of firm support body to body massage centres near me and gentle rocking motions helps create a secure and nurturing environment.

lishasingh said...

Pain Management: Exploring how touch-based techniques massage parlour near me can alleviate physical discomfort and pain by enhancing the body's natural healing processes.

rennasweety said...

It is used by couples all over the world spa near me as a way to enhance romantic and sexual life.

nancysweety said...

Baring all to a stranger can be hugely adultmassage in pune liberating and really make a difference to self-esteem. You’ll never shy away from disrobing in the same way again.

lipikabri said...

Although the focus of forest therapy isn’t female to male body massage in hyderabad on physical exercise, regular practice can help you lead a less sedentary lifestyle, too.

lipikabri said...

Although the occasional forest therapy outing female to male body massage in hyderabad may help you unwind for a few hours,

westcoastwatersafety said...

School Water Safety WA is a program that focuses on promoting water safety in schools. It aims to educate students about the importance of water safety and provide them with the necessary skills to stay safe in and around water.

The program includes various activities and resources that are designed to engage students and teach them about water safety in a fun and interactive way. School Water Safety WA is committed to ensuring that all students have the knowledge and skills they need to enjoy water activities safely.

unknown said...

The documentation provided by this
dissertation writing service is truly exceptional! It's a valuable resource that greatly enhances the overall quality of the service. Comprehensive and well-organized, it proves to be an invaluable aid for anyone navigating the complexities of academic writing.