Re: the character ‘%’

[Paul Smith]

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 <address@hidden>          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