>> Yeah. That's definitely a change driven by new hardware paradigms, 
>> tho. Besides that obvious change, what else, tho?  What would make it 
>> easier to write documentation?
> 
> Docman? Javadoc?

Well now, there are basically two ways to do documentation:

1. Have the source code, and a seperate set of documentation files.

2. Have the documentation text mingled with the source code text.

Method #1 suffers from the problem that the source code inevitably gets 
updated more than the documentation, until the two end up being out of 
sync. Incorrect documentation is worse than absent documentation.

Method #2 suffers from the problem that there's so much chatter in the 
source file that you can't actually find the executable code any more. 
It makes small, simple modules look huge and complex.

I can't think of a good way to solve this. Sure, you could have some IDE 
where when you change a file, you can add a note to self to update the 
documentation. But if the human forgets to add that note...

-- 
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*

Post a reply to this message