udoc

Udoc is the name of my latest program to do literate programming, and I'm reusing it here, for writing about the subject. It is perhaps not a very good name, but I used it since the subject is such a many-faceted one:

API documentation is what I did at Trolltech. At least that's what I thought I was doing at the start. As I was developing the format and writing text, I found I could use the documentation for two other purposes:

Maintainer documentation is one half of what Abhijit and I do for Archiveopteryx.

Writing better code through writing documentation and thereby developing a better understanding.

Checking boxes is what I see much too often. There Shall Be Documentation, or I Will Document My Code; but the actual documentation is meaningless — doesn't answer any questions I have about the code or interface.

Literate programming tools can be used for all three. Some are better suited to one purpose, some to another. Disciplined usage can help reach a goal even if the program fails to help — I still think it's a failure, though.