website | twitter

Wednesday, August 13, 2008

What does documentation lose?

I realized that Knuth emphasized narrative way to express a program documentation instead of formal way in "Literate Programming" paper. The reason why WEB needed macro mechanism which Pascal didn't have was that it was needed to make the program flexible enough so that an author can keep order of original thinking flow on the text. Using WEB, whatever each symbol dependents on others, you can write down in any order which you like.

a program is, likewise, ready to comprehend it by learning its various parts in approximately the order in which it was written. -- LITERATE PROGRAMMING

Such consideration have been lost in current documentatin mechanisms like JavaDoc. Major goal of documentation generator for programming language is to make a comprehensive reference, certainly, literary value would be out of scope in those systems. I expect thet My Active Essays project would be a missing link following the lost feature.

However, before diving too deep, I need to know current art and science of program documentation... to be countinued.

1 comment:

 
Creative Commons License
This work is licensed under a Creative Commons Attribution 3.0 Unported License.