Book Comprehensibility WAS Unable to compile GCC

Mike McCarty Mike.McCarty at sbcglobal.net
Mon Mar 29 07:17:45 PDT 2010


Simon Geard wrote:
> Well, if we're seeing people being confused by what 'source directory'
> refers to in this case, it's probably worth trying to clarify it a
> little. Even a single-word change like the following might help:
> 
>     "The GCC documentation recommends building GCC outside
>     of it's source directory in a dedicated build directory."
> 
> 
> To me, replacing "the" with "it's" makes is much clearer that it refers
> to GCC's source directory, not to the higher-level one containing the
> tarballs.

It helps some, but perhaps not quite enough.

In order to help clarify what's going on, I want to express a little
of my own experience, and background. The point of this next bit is
to show that a non newbie might actually be confused by the book,
and to stop that part of the argument altogether.

First, I'm a native English speaker. It is my second language, but I
began speaking it when I was about three, and it is my preferred
language.

Second, I'm experienced in writing software requirements, design, and
also in implementation. I've worked in the OS and driver area dealing
directly with hardware for a number of years. I wrote a small real time
multitasking OS in 1984 or so, and worked with various kernels and
drivers doing hard real time for about 15 years in telecomm, using
various mixtures of C and assembler. I've used UNIX like operating
systems for about the same period of time.

Third, I've written a few pieces of user documentation over the years.

Fourth, I read every single word in the book, some of them more
than once.

I had a little trouble understanding just which directory was meant.

If I had a problem, then this is not an issue of newbies. It is not
a problem of not reading the book. It is a problem with the wording
of the book. I believe that I am a part of the target audience,
perhaps a little cut above most in some of my experience.

I also understand the reluctance to take complaints, rather than
contributions. The statement

	This isn't clear, rewrite it until I like it.

is not helpful. We used to complain bitterly about users who would
complain that our software wouldn't do what they want, but who also
would not supply verifiable requirements. We had little cartoons
up all over with

	Customer: Bring me a rock.
	Guy brings back a fist sized rock.
	Customer: No, I need a bigger one!
	Guy brings one so large, he's carrying it on his back. It's
		practically a boulder.
	Customer: No, I need a smaller one!
	Guy throw up his hands in disgust and walks away.

Complainers are not helpers, and helpers are not complainers.
There is a difference between a complaint and a criticism.

I think this situation is somewhat similar. "Make it clearer"
is not a requirement, and there is no way anyone can know whether
his rewrite is any clearer to someone else. Suggestions for
rewording are an entirely different matter. Like the one
to include "its" in the phraseology.

I think the book is a marvelous thing. I also believe that it
is to some degree a little terse. Terseness has many advantages,
but understandability is not usually one of them. Excessive wordiness
is just as bad, since details get buried in words. So, terseness is
a good thing, generally. Excessive terseness leaves the reader
wondering if he filled in the gaps in the right way.

This is perhaps one of those places, and sometimes an example goes
a long way to helping fill in the gaps. I'm not sure that having
examples for each of the software packages is a good way to handle
that. However, having one example, or at least more words, in the
general description of the kind of "exception to the rule" that
will be encountered, to explain what is meant, might strike the
right compromise between terseness, and maintainability of the
book on the one hand, and wordiness which is hard to maintain
and buries details in the words on the other, and yet improve
understandability.

I intend to spend some time reading the latest version of the
book and see whether I may be able to make a suggestion along
these lines.

Mike
-- 
p="p=%c%s%c;main(){printf(p,34,p,34);}";main(){printf(p,34,p,34);}
Oppose globalization and One World Governments like the UN.
This message made from 100% recycled bits.
You have found the bank of Larn.
I speak only for myself, and I am unanimous in that!



More information about the lfs-support mailing list