Re: Do have programs have poor documentation?

From	Xen <list@xenhideout.nl>
Newsgroups	linux.debian.user
Subject	Re: Do have programs have poor documentation?
Date	2017-01-01 12:40 +0100
Message-ID	<sUMEy-8cm-15@gated-at.bofh.it> (permalink)
References	<sUoiR-18f-9@gated-at.bofh.it> <sUpyh-1Ov-3@gated-at.bofh.it>
Organization	linux.* mail to news gateway

Show all headers | View raw

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.

Thread

Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-16 15:20 +0100
  Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-16 16:00 +0100
    Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-16 16:20 +0100
      Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-16 19:40 +0100
        Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-17 13:20 +0100
          Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-17 15:30 +0100
            Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-17 15:50 +0100
    Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-17 15:50 +0100
      Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-17 17:40 +0100
      Re: Why? -- "A Modest Proposal" Curt <curty@free.fr> - 2016-11-17 18:10 +0100
      Re: Why? -- "A Modest Proposal" kamaraju kusumanchi <raju.mailinglists@gmail.com> - 2016-11-22 06:40 +0100
  Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-16 16:40 +0100
    Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-17 16:00 +0100
      Re: Why? -- "A Modest Proposal" "John L. Ries" <jries@salford-systems.com> - 2016-11-17 19:00 +0100
        Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 22:40 +0100
        Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:40 +0100
        Re: Why? -- "A Modest Proposal" rhkramer@gmail.com - 2016-11-18 00:10 +0100
      Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:30 +0100
        Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 22:40 +0100
          Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:40 +0100
            Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 23:00 +0100
              Re: Why? -- "A Modest Proposal" Reco <recoverym4n@gmail.com> - 2016-11-18 09:20 +0100
          Re: Why? -- "A Modest Proposal" rhkramer@gmail.com - 2016-11-18 00:10 +0100
  Re: Why? -- "A Modest Proposal" emetib <chadbrabec@gmail.com> - 2016-11-18 09:50 +0100
    Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-18 10:40 +0100
    Re: Why? -- "A Modest Proposal" "Thomas Schmitt" <scdbackup@gmx.net> - 2016-11-18 11:10 +0100
      Re: Why? -- "A Modest Proposal" emetib <chadbrabec@gmail.com> - 2016-11-18 20:30 +0100
      Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") cbannister@slingshot.co.nz - 2016-12-29 15:10 +0100
        Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:10 +0100
        Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:10 +0100
          Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-29 19:40 +0100
            Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:40 +0100
            Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:40 +0100
              Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-29 19:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-30 02:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 03:30 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 03:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Greg Wooledge <wooledg@eeg.ccf.org> - 2016-12-30 15:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 18:00 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 15:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 16:00 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") John Hasler <jhasler@newsguy.com> - 2016-12-30 17:20 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:30 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 09:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 10:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-31 17:20 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:00 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:20 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 14:00 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Nemeth Gyorgy <friczy@freemail.hu> - 2016-12-31 10:40 +0100
                Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2016-12-31 12:00 +0100
                Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 12:40 +0100
                Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 14:10 +0100
                Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 19:10 +0100
                Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 20:50 +0100
                Re: Do have programs have poor documentation? Gene Heskett <gheskett@shentel.net> - 2017-01-01 15:10 +0100
                Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 20:50 +0100
                Re: Do have programs have poor documentation? Gene Heskett <gheskett@shentel.net> - 2017-01-02 02:10 +0100
                Re: Do have programs have poor documentation? Lisi Reisz <lisi.reisz@gmail.com> - 2017-01-02 02:30 +0100
                Re: Do have programs have poor documentation? David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 16:00 +0100
                Re: Do have programs have poor documentation? rhkramer@gmail.com - 2017-01-02 17:30 +0100
                Re: Do have programs have poor documentation? David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 18:20 +0100
                Re: Do have programs have poor documentation? rhkramer@gmail.com - 2017-01-02 18:50 +0100
                Re: Do have programs have poor documentation? Eike Lantzsch <zp6cge@gmx.net> - 2017-01-01 18:00 +0100
                Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 19:30 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-31 15:20 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 12:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 15:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2017-01-02 17:20 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 18:10 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2017-01-02 18:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Jörg-Volker Peetz <jvpeetz@web.de> - 2017-01-02 19:10 +0100
        Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-30 02:40 +0100
          Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 03:30 +0100
            Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-30 18:30 +0100
              Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") Dan Purgert <dan@djph.net> - 2017-01-01 12:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 12:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 14:10 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 15:10 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 16:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 17:20 +0100
                [OT] on education [was]: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 20:40 +0100
                Re: [OT] on education [was]: Do have programs have poor  documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 23:50 +0100
                Re: [OT] on education [was]: Do have programs have poor  documentation? (was ... Re: Why? -- "A Modest Proposal") Joel Rees <joel.rees@gmail.com> - 2017-01-02 01:30 +0100
              Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Rob van der Putten <rob@sput.nl> - 2017-03-12 17:50 +0100
            Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:30 +0100
              Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 10:30 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:00 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2017-01-01 13:00 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:30 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 14:20 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 18:00 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <xen@dds.nl> - 2017-01-01 20:10 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") Bob Holtzman <holtzm@cox.net> - 2017-01-02 20:40 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A Modest Proposal") cbannister@slingshot.co.nz - 2017-03-11 10:00 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Martin Read <zen75502@zen.co.uk> - 2017-03-11 12:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-03-11 14:30 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Doug <dmcgarrett@optonline.net> - 2017-03-11 19:30 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? --  "A  Modest Proposal") Dan Purgert <dan@djph.net> - 2017-03-13 13:10 +0100
          Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-30 04:40 +0100
            Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:40 +0100
          Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 12:40 +0100
            Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Richard Owlett <rowlett@cloud85.net> - 2016-12-30 13:30 +0100
              Re: Do have programs have poor documentation? (was ... Re: Why? --  "A  Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 15:50 +0100
            Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
              Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-30 20:50 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 00:20 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-31 01:10 +0100
                Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 01:50 +0100
                [OT] Antikythera mechanism [was Re: Do have programs have poor  documentation?] Miles Fidelman <mfidelman@meetinghouse.net> - 2016-12-31 03:20 +0100
                Re: [OT] Antikythera mechanism [was Re: Do have programs have poor documentation?] deloptes <deloptes@gmail.com> - 2016-12-31 10:20 +0100
        Re: Do have programs have poor documentation? (was ... Re: Why? -- "A  Modest Proposal") Rob van der Putten <rob@sput.nl> - 2017-03-11 22:50 +0100
  Re: Why? -- "A Modest Proposal" kamaraju kusumanchi <raju.mailinglists@gmail.com> - 2016-11-22 07:10 +0100
    Re: Why? -- "A Modest Proposal" Darac Marjal <mailinglist@darac.org.uk> - 2016-11-22 13:00 +0100
    Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-22 13:30 +0100

csiph-web