Re: the character ‘%’

[John Calcote]

 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