On Sat, 2010-08-21 at 14:13 +0430, ali hagigat wrote: > Each explanation has some components. An explanation is written IF AND > ONLY IF its components have been written and explained FIRST.
If you ever try to write documentation for a complicated software package such that it follows this simplistic rule, then that will be something I'm interested in reading. You have two main methods that can be used for documenting complex things. The first is a "top down" method where you start with the big picture, then progressively get more detailed until all is explained. In this method there is no way to explain everything completely before you refer to it in some other context. This is (more or less) the method that the GNU make manual attempts to use. The second is to go "bottom up", and explain all the detailed parts first, then build on top of those to ever more increasing complexity. This seems to be the method you'd prefer. I don't think that the second method leads to readable documentation. For a complex system like make you'd basically be documenting a number of completely disjoint subjects with no way to tie them all together, just to ensure that all elements were explained before any element was referred to. By the time you got around to explaining why some subject 25 pages ago was used, it would have been forgotten anyway. To me this is confusing and, frankly, boring... people want to know why something is useful when they learn about it, not several chapters down the road. In the GNU make manual we take a "top down" approach, and we add in extensive cross-referencing and large indices. These are very easily followed/referred to if you use any decent documentation reading software; also searching is quite simple of these fail you. So, if you run across a term you don't understand you can search for it in the index, or follow a cross-reference, or even search the entire manual. Or, you can just accept that you don't understand that particular thing yet but that it will be explained later, put it aside mentally, and continue on reading. -- ------------------------------------------------------------------------------- Paul D. Smith <[email protected]> Find some GNU make tips at: http://www.gnu.org http://make.mad-scientist.net "Please remain calm...I may be mad, but I am a professional." --Mad Scientist _______________________________________________ Help-make mailing list [email protected] http://lists.gnu.org/mailman/listinfo/help-make
