Diego Novillo wrote:
We are already having trouble keeping our documentation up-to-date. Some of it is in such a poor shape as to be laughable. Yes, it's mostly our fault, but if we were able to generate documentation by simply extracting it from the code. Tools exist for this, and properly maintained, they are very useful.
I am actually a bit dubious about automatic extraction of documentation from code. The kind of thing you can get this way is in any case easily obtained by browsing the code. All too often this kind of automatic generation is just a way of satisfying the need for quantity of documentation without enough attention to quality. There are certainly exceptions to this, some of which have been mentioned in this thread, but as a general mechanism, it is dangerous in my opinion. Ultimately the proper path to excellent documentation is to have programmers who are as interested in generating documentation as they are in writing code. If you don't have that, you will never get really good documentation.
