Jan Nieuwenhuizen <[email protected]> writes: > Graham Percival writes: > >> No argument there! Yes, more documentation about maintainability >> the better. > > I hope you're joking... The less documentation needed, whether it be > for program usage, describing program bugs, build or release process, > or maintainability, the better. No one likes to read documentation.
It beats reading code. Code is written for computers, documentation for humans. Computers are perfectly able to get along following instructions. They don't need to understand anything. Continued development and maintenance, in contrast, requires understanding. > What is really bad, is a situation where doing one of these things > becomes some sort of puzzle, maze, time sink of trial and error, that > could have been avoided by adding or sharing some minimal piece of > documentation. If you take a typical look at Keith reviewing Mike (happens only if the reviewing period time of a patch stretches over a weekend where Keith has time), you'll find that Keith is asking a number of questions about how the code is supposed to work that are documented nowhere. Mike then congratulates Keith on figuring out the puzzle correctly (or not) and everybody is happy. Again and again and again. Drives me nuts. > However, documenting something that can also be automated is bad. Sure. Having to make decisions is work. A good interface will offer only decisions for cases of fundamental different nature. Not decisions about picking between two choices doing the same job with different shortcomings. > Fixing a bug is much better than adding documentation about how to > work around it. If you are tempted to document something, start with > /why/ Sure. That's the one thing one does not need to tell the computer via code. But that is still part of the story. -- David Kastrup _______________________________________________ lilypond-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-devel
