On 8/28/2010 5:42 PM, Paul Smith wrote: > 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.
There is a third method: You begin by showing examples of how common tasks might be performed using the tool, and explain concepts and processes along the way. When you need to explain a new process or concept, you contrive an example that will allow you to explain the target concept in the context of the example. This is actually the method most conducive to human learning. However, it's very difficult to create a cohesive reference manual using this technique. Thus, software manuals written the way Paul suggests - in a top-down fashion - make the best reference manuals, but can effectively be supplemented by third-party books, written in the format I've described - teaching by example. Unfortunately, if a reference manual provides an example for every key concept it must present, it would be 3 times a thick, and half as useful to those who already know the concepts, but need to look something up. Examples help us to correlate new information with information we've learned from past experiences. This correlation cements the desired new concepts into our memories much quicker than information presented to us without such context. This is why a good teacher is often a good story teller. Note that even using stories for which we have no experiential frame of reference would not be helpful, however, it's difficult for human beings to contrive such abstractions. (Though I've read my share of Si-Fi stories that I had to work really to get my head around.) John _______________________________________________ Help-make mailing list [email protected] http://lists.gnu.org/mailman/listinfo/help-make
