Re: Do have programs have poor documentation?
On Sunday, 1 January 2017 12:36:51 PYST Xen wrote:
> Thomas Schmitt schreef op 31-12-2016 11:59:
> > Well, "info" is the pet of GNU and thus often better documentation for
> > GNU tools than their "man" pages.
> > The goal and viewpoint is nevertheless the same: Technical
> > documentation
> > of programs, not tutorial.
>
> I personally also cannot use "info". I have tried many times in the
> past. Always gave up pretty quickly. Just unusable to me.
>
> I would need to study a tutorial on how to use info and I don't even
> want to.
>
> > The reason why many large man pages or info documents are so hard to
> > grasp is really in the difference of viewpoints. Too much background
> > knowledge and too exotic programmer's motivations, i assume.
>
> Yes exactly. You are assumed to already know the program when you start
> reading the man page.
>
> You are assumed to know everything the programmer knows. This is the
> "Linux is easy" fallacy that originates from people forgetting how long
> it took them to acquire some knowledge, and now they think it was easy
> all this time for them, but they had to become familiar with it at first
> as well.
>
> For example, if you are new to LVM, and you are in some rescue mode that
> doesn't automatically activate your volume groups, doing "vgchange -ay"
> is not that intuitive. "man lvm" is also not helpful. You will first
> need to find the required command (vgchange) before you can get any
> help, but you don't know that you need that one because you don't feel
> you want to change the vg, you only want to activate it. This can
> quickly elude you for some time and especially if you are in a pinch and
> suffering already, you may not have the time and mental capacity for it.
> You are trying to rescue your system and cannot find the tool to do it
> with, but you don't have internet so you can't look it up and.....
>
> Then some fool will later day: "Why don't you just do vgchange -ay?" And
> if you then say "Well that is not that easy to know" they will say "man
> vgchange" "easy".
>
> > Nevertheless i suffer like most other people when i have to study
> > foreign
> > technical docs for the first time.
> > So it is not dumb user versus smart programmer but rather insider
> > versus
> > newcommer.
>
> Yes, exactly.
Interestingly enough the motto of 33. Chaos Communication Congress in Hamburg
was: "Works for me". They aimed at getting programmers out of their lethargy
because their software not only has to "work for them" but also for everybody
else. An interesting write-up is here:
https://www.heise.de/newsticker/meldung/33C3-Hacker-greifen-nach-der-grossen-politischen-Nummer-3579778.html?wt_mc=rss.ho.beitrag.rdf
Unfortunately only in German but Google Translate might help. Well maybe not
so much with "The Awful German Language" [tm Marc Twain]
Cheers
Eike
--
Eike Lantzsch ZP6CGE
Asuncion / Paraguay
“Do you actually know what you are reading?”
He said: “Really, how could I ever do so unless
someone guided me?” ... (Acts 8:30, 31)
Reply to: