Arnt Gulbrandsen
About meAbout this blog

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.