[doc] Addressing users [Was: Re: I don't think that a wiki page for HardwareSupport is that a good idea]

[Enrico Zini]

On Thu, Oct 21, 2004 at 07:29:05AM -0700, Darren Critchley wrote:

> I definitely agree with you, many open source projects have the 
> documentation written by experts who take too much for granted. I think 
> all documentation, help, how to's, etc should be written with the target 
> audience being newcomers. For people who have the knowledge, that is a 
> hard lesson to learn, I had to learn this myself when I wrote several 
> how to's on various vpn connections to a firewall project I work on, you 
> cannot take anything for granted, even setting file permissions has to 
> be explained.

If you write things for newbies talking as if they were experts, they
won't understand; if you write to experts as if they were newbies, they
won't find enough informations.  The solution is just writing to the
right target in the right way, and make it clear who we're writing to.

This means two things:

 1) We need to decide who we are writing to
    (an "iptables tutorial" is not going to take off if addressed to
     newbies of computing, no matter how simple you can put it[1])
 2) We need to be consistent in our selection
    (avoiding to write a document for newbies with digressions into
    super-expert mode, or to give for granted impossible things just
    because the documentor is lazy[2])

I hope this is an acceptable solution for this problem.  Also, since
we've been talking about newcomers and experts but the "users" crowd is
a bit more diverse, I've added a new page in the Wiki with a more though
classification: http://wiki.ubuntulinux.org/StagesOfUse


Ciao,

Enrico


[1] If the need arises, a good strategy may be in documenting (or
creating and documenting) an ad-hoc application for those specific goals
a newbie may need to attain with iptables
[2] Bad example: "Cookie privacy for dummies -- To read this document
you need a basic understanding of the HTTP protocol and server-side
scripting"
--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.ubuntu.com/archives/ubuntu-devel/attachments/20041021/2720913e/attachment.pgp