Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

In a similar vein as the Why do many open source projects have no 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.

share|improve this question
5  
Maybe because you and I have spent so little time writing documentation for open source libraries. –  Eric Wilson Aug 16 '11 at 13:19
    
Because writing good documentation is hard, so most developers solve that problem by just not doing it. Besides, everything seems obvious while you're in the middle of writing the code. "My library is so easy to use that it's self-documenting!" -- Yeah, right. –  Cody Gray Aug 16 '11 at 13:56
    
I don't entirely agree with your view, especially your third point. Writing code isn't always easy. –  Bernard Aug 16 '11 at 18:39
add comment

6 Answers

up vote 15 down vote accepted

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.

share|improve this answer
    
So what you're saying is, that the developer isn't really thinking about how their library would be used by people other than themselves in the first place? –  Billy ONeal Aug 16 '11 at 8:26
    
@Billy: Frequently yes -- or at least they often tend to think of it only in a rather fragmented fashion -- how somebody will use an individual function, not an overall approach to use the entire library. –  Jerry Coffin Aug 16 '11 at 8:38
add comment

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!

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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".

share|improve this answer
add comment

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 ...

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.