Most documentation fails in giving too little overview.
The trees are described, the bark and leaves are commented, but there is no map of the forest.
- p.165 The Mythical Man-Month (ch 15, Anniversary Ed.) Some is dated, but like the rest of the book, most is incredibly modern.
Totally agree about lack of overview. eg. Java's docs on JTree are detailed and there is no shortage of tutorials and samples online, but I've yet to find an overall description of how it fits together. One has to piece it together from carelessly left clues.
Auto-generated documentation can be quite useful for working out how things fit together, and you can click through linked types to follow the connections. This is one advantage of statically typed languages like Java (bonus: combining source and doc-comments - "literate programming" - keeps them synchronized, or helps to). I often scan javadocs by return type and/or arg types to find the method I need. Haskell has an amazing doc tool where you enter the type signature, and it tells you the functions that match. (BTW: I love this, but do haskellers find it useful on real-world projects, in practice?) Python benefits greatly from not having static types; this is one of the few disadvantages.
The author was honest enough to admit some particulars where he didn't follow his advice. It's easy to advise on the right thing to do, but if you find it difficult to get it done yourself, is it really practical advice, under real-world pressures, on those particulars? Else we mouth an empty folklore, like Catmull's architect who said to design "inside out" but didn't.
- p.165 The Mythical Man-Month (ch 15, Anniversary Ed.) Some is dated, but like the rest of the book, most is incredibly modern.
Totally agree about lack of overview. eg. Java's docs on JTree are detailed and there is no shortage of tutorials and samples online, but I've yet to find an overall description of how it fits together. One has to piece it together from carelessly left clues.
Auto-generated documentation can be quite useful for working out how things fit together, and you can click through linked types to follow the connections. This is one advantage of statically typed languages like Java (bonus: combining source and doc-comments - "literate programming" - keeps them synchronized, or helps to). I often scan javadocs by return type and/or arg types to find the method I need. Haskell has an amazing doc tool where you enter the type signature, and it tells you the functions that match. (BTW: I love this, but do haskellers find it useful on real-world projects, in practice?) Python benefits greatly from not having static types; this is one of the few disadvantages.
The author was honest enough to admit some particulars where he didn't follow his advice. It's easy to advise on the right thing to do, but if you find it difficult to get it done yourself, is it really practical advice, under real-world pressures, on those particulars? Else we mouth an empty folklore, like Catmull's architect who said to design "inside out" but didn't.