Why do so many libraries have no/poor documentation? [closed]

Question

In a similar vein as the How can open source projects be successful without documentation about their design or architecture? question, I'm curious: Why are so many libraries so lacking in end user documentation?

My view is this:

1. Most everyone agrees that reading source code is more difficult than writing source code.
2. Without documentation, one must read the library's source code in order to use that library.
3. Therefore, using the undocumented library is more work than just recreating the library from scratch.
4. As a result, if you want to have people use your library, you'd damn well better make sure it's documented.

I know lots of developers don't like writing docs, and I'll agree it can be tedious work. But it's essential work. I'd even say it's more important that a library have good documentation than have the best programmer's interface in the world. (People use shitty libraries all the time; few use undocumented libraries)

Oh, note that when I say documentation, I mean real documentation. Not Sandcastle/Javadoc/Doxygen boilerplate.

Answer 1

I think you've mostly answered your own question: because in most cases, developers just won't bother. The problem is especially prevalent in volunteer projects.

I do think there's another major problem though: in a lot of cases, developers haven't really developed an overall model of how their library works (or just have difficulty articulating that model clearly). Unfortunately, articulating that model and how the pieces of the software fit together is often the most important part of the documentation.

In a typical case, what's written has a very high-level overview ("This is a library for doing cool stuff!") and then a very low-level description (type and description of each parameter to be passed to each function). Unfortunately, there's rarely an intermediate level about the general theory of how things are supposed to work, how the pieces fit together, etc. Much of this goes back to the fact that developers often haven't attempted to form, rationalize, or understand their code at that particular level of detail. At least in some cases I've seen, developers who were asked to write documentation at that level found it quite problematic -- to the point that many wanted to rewrite the code so it would be more organized and easier to explain at that level of detail.

Writing well at that level of abstraction is often difficult -- and if the developer hasn't really thought about it at that level of abstraction, they'll often find the code somewhat embarrassing, and might want to rewrite it before they're happy about releasing it at all.

Answer 2

I think sometimes it's because the developer is so wrapped up in the code that it's "obvious" to him/her how it works and they can't see why it wouldn't be obvious to anyone else. Similarly, loads of product web sites say how wonderful their product is, but don't actually tell you what it does!

Answer 3

You pointed out the answer yourself:

I know lots of developers don't like writing docs, and I'll agree it can be tedious work.

As programmers, we enjoy writing code, but very few of us also enjoy writing documentation.

While any good coder knows the value of good documentation, it also takes a fair amount of time to do it properly. As it's not enjoyable and takes a long time, it gets put in the "to do later" pile so it never gets done to a satisfactory level.

As a side note, it's also very hard for a programmer to write documentation on their own product. As they know the system so well, certain things are obvious to them. These parts often never get mentioned despite not being obvious to the consumer.

Answer 4

Writing documentation is a skill. Like all skills it takes practice. The time and effort we spend writing code has a immediate pay off. We can see the new feature, the fixed bug, the improved speed. Writing documentation has a delayed payoff. It helps in the long run as new people need to work on the code or if we come back to work on the code months or years latter. It is only natural we focus on the short term.

In my opinion, the ability to write good documentation it one of the key traits that distinguishes great programmers from mediocre programmers.

Answer 5

The person who is best qualified to write documentation is also the person who has the least motivation for doing so:

he (or she) is:

• primarily a maintainer of the library, rather than a user. So the smaller and simpler the library is, the easier his job. Maintaining half a novel in addition to the code only makes his job harder,
• he knows the library inside out, so he doesn't need the documentation,
• he's a programmer, he wants to write code, not documentation.

I can't think of anyone who's less likely to go "Hmm, I really should spend a few hours writing some proper documentation for this". Why would he?

And of course, it probably doesn't help that there's this urban legend going around that autogenerated doxygen-style comments are all you need in terms of documentation.

So even in the rare cases where a developer is actually willing to write documentation, it's a 50/50 chance that the developer has been brainwashed by this cult into thinking that all that is needed is filling out a few such comments, telling you gems like that "the function Foo getFoo() returns an object of type Foo, and it is used to get the Foo object".

Answer 6

Documentation? We don't need no stinkin' documentation!

I know how the code works, so why would I spend time documenting my code? Besides that, I've got to have this project done by Friday and I'm barely going to make it as it is ...