Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal")

[cbannister@slingshot.co.nz]

On Sun, Jan 01, 2017 at 12:52:20PM +0100, Xen wrote:
> Lisi Reisz schreef op 31-12-2016 10:30:
> 
> >Which make me bad at writing?
> >
> >Lisi
> 
> Refusing to write good documentation on purpose.

Oh, come on! What you call good documentation means
writing for a user who has no clue about what the
program does.

Imagine a recipe written for a user who has no clue
about cooking ... I mean where do you start? You
HAVE to assume the reader has a certain level of
expertise.

Some man pages do have an EXAMPLE section which
can be very helpful.

It's a waste of time discussing what a man page should
be; it's already perceived as a reference document.

I too was in the same dilema when I first started using
Linux, even 'spoon feeding' tutorials introduced terms
which were new to me. The onus was on *me* to 'understand'
the material. There is plenty of info out on the Internet,
and I find appropriate blogs give a lot of good introductory
material/links to help me with that.

I've seen the quote: "I can explain it to you, but I
can't understand it for you' OK, it is a bit blunt.

-- 
The media's the most powerful entity on earth. 
They have the power to make the innocent guilty 
and to make the guilty innocent, and that's power.
 -- Malcolm X