Re: [Groff] colored background?

[Clarke Echols]

Miklos Somogyi wrote:

> Yep, colour, just like anything else, can be abused. Also, colour can be 
> elegant
> and its consistent and moderate use can help organize one's text very well.
>
> White only can be very boring, and by lack of its visual clues it would 
> want one
> read the whole thing again when one only wants to find something specific.
> If anything out of the white legacy thing is gimmick, then I want my 
> word processor
> to learn a lot of gimmicks.
> If one talks about 3d relationships, nothing beats a 3d sketch that is 
> as clear as possible,
> whether one wants to brag about what his/her word processor can do.
>
> Yep, I would not want anyone not to make their thoughts as accurate and 
> precise as they can,
> but would much welcome formatting efforts that would give readers an  
> instant recognition
> of this or that. This does not have to be graphics, e.g. considerate 
> naming of files too would do a good job, e.g.
>
>    ln -s existing-file newly-created-pointer

This is exactly the sort of thing I did in the HP-UX reference in the
early 1990s.  For SYNOPSIS on cp(1), for example:

   cp filename newfilename
   cp file1 file2 ... directory
   cp file1 directory2 ... new_directory

etc.

A lot of readability has to do with paragraph length (keep them
short where possible or break them up), using bullet lists,
tagged paragraphs (.TP macro), and proper use of fonts for
clarity of meaning.

Subtle use of shading is also helpful where practical, but don't
overdo it.

It is difficult for an engineer to create really excellent
documentation unless he or she is familiar with the principles of
quality presentation methods.  Likewise, "technical writers" with
English or journalism degrees who don't know computers and software
thoroughly don't make good manual writers either.

When writing manuals, help, etc., the writer is a *teacher*.  You
cannot successfully teach what you don't know and thoroughly
understand.

And your teaching won't be effective if you aren't a master at
communicating your meaning clearly, accurately, and in an
easy-to-understand way.

My method was to remain what I called "intelligently stupid".  I
put myself in the shoes of the reader and asked myself, "What does
my reader need to know to be successful.  Now how do I transfer
that knowledge to him or her in a way that I cannot be misunderstood."

That also means carefully looking for any possible ambiguities in
what you are saying or explaining, so that the person cannot be
confused in an abnormal situation.  You *must* cover *every* possible
screwy angle.

I recall a manager coming to me with confusion about something in
"vi".  He was using a "Beginner's Guide" that someone had adapted
from my vi book.  The author thought some of my words were unnecessary
and took them out.  They were in the original book to prevent *exactly*
the ambiguity the confused manager had encountered.

That's why I always insisted to other writers, "Don't mess with
my words without asking me first."

Clear, correct communication is an art form.  And I have great
empathy for those who must attempt to communicate in English when
it is not their primary native language.  The Germanic languages
don't have the many complexities we have to deal with.  (I speak
Danish -- learned it while in Denmark 1963-1965.)

Clarke