Re: newbies/advanced users: for whom we write?

[John Fleck <jfleck inkstain net>]

On 9 Mar 2000, Alexander Kirillov wrote:
> while reading some of GNOME manuals, I realized that they were written
> by developers for other developers, with little understanding of level
> of average user. Thus, I'd like to include in the Handbook some
> guidelines about what the documentation authors should expect from the
> reader. 

I think the approach Sasha is suggesting here is a good one in several
regards.

First, I think it's appropriate, as he did, to give a number of concrete
examples (PID etc.) of the sort of jargon new users might not understand.
Concrete is good as a reminder for authors who may have been too immersed
in the jargon for too long to realize it's wet down there....

Second, the idea of a "basic usage" and "advanced usage" distinction within
documents suggests a promising approach, so that each of the possible
audiences will have their needs met.

Can I suggest including, in the handbook, a link to a completed application
manual that demonstrates this approach? Templates are fine for
demonstrating proper sgml, but this requires a different sort of
demonstration.

-- 
John Fleck
jfleck@inkstain.net
www.inkstain.net