Re: Do have programs have poor documentation?

From	"Thomas Schmitt" <scdbackup@gmx.net>
Newsgroups	linux.debian.user
Subject	Re: Do have programs have poor documentation?
Date	2017-01-01 14:10 +0100
Message-ID	<sUO3D-JY-1@gated-at.bofh.it> (permalink)
References	<sUMEy-8cm-15@gated-at.bofh.it>
Organization	linux.* mail to news gateway

Show all headers | View raw

Hi,

Xen wrote:
> I personally also cannot use "info". I have tried many times in the past.

That's why i fulfill the requirement of GNU to have an info documentation
by writing a single .texi document for both, info and man. (This needs
a specialized postprocessor to derive .1 from .texi .)
The text content of xorriso.1 and xorriso.info is the same. Only the
presentation differs.

Reading a man page and searching in it just needs the ability to operate
the "less" text viewer. The same job in "info" needs the will to navigate
by a non-graphical text browser.
If you want to learn background, the hierachical format seems somwhat better.
But if you want to know what a certain xorriso command does, then you are
better off with the man page and "/" for searching.

> I would need to study a tutorial on how to use info and I don't even want
> to.

This is a general example why it is so hard to satisfy the users'
documentation needs.

>From the viewpoint of "info" programmers it is obvious that you first
have to learn how to use it before you can draw benefit from it.

But the particular user has a particular need to get information about
a particular complex of problems. No interest in learning anything else
before the current task is completed.

Now how shall the provider of software documentation handle this conflict ?

There are various approaches from books over wikis to community discussions.
As much as they serve additional groups of users, that much they diversify
the landscape of available information sources. They begin to contradict,
spread half-knowledge, or even engage in advertising wars. (The classic
"use original cdrecord" which you can read with many problem discussions
about optical media.)

I decided for massive man pages and using Google to find public discussions
about my software and related topics. If i find such discussions, i try to
determine impartially the cause of the problem and to propose a remedy.
If that remedy means "use original cdrecord" then be it so.
But in most cases it's "get other media or a new burner drive".

> You are assumed to already know the program when you start
> reading the man page.
> You are assumed to know everything the programmer knows.
> [...] "vgchange -ay" [...]

I dare to contradict. Not your assessment that man vgchange is hard to
digest, but your impression that the programmers or documenters don't care
for your initial lack of knowledge.

They try to teach us. With limited success. But nevertheless:
  "vgchange allows you to change the attributes  of  one  or  more  volume
   groups. Its main purpose is to activate and deactivate VolumeGroupName,
  "
Duh ?
  "See lvm(8) for common options."
Oh. It has family.
  "lvm  provides  the command-line tools for LVM2."
Now it would be time for me to learn some basics about a thing named "LVM2".

A few days later i would possibly be able to roughly understand what the LVM
developers invented during the last two decades and how my current problem
is related to this invention.

But:
> you are in some rescue mode that doesn't automatically activate your
> volume groups,

Here we see why old programmers try to avoid using fancy infrastructure.

The answer in an ideal world would be: Learn how to rescue yourself before
the ship begins to sink.
This does not necessarily mean to master LVM and all other probable points
of failure. It means to have a fallback strategy that reduces your personal
stress level in case of emergency.

In my case it's a pile of backups and the presence of readily configured
reserve hardware. (I should do emergency exercises more often.)

Be aware of what you depend on and prepare for temporarily losing it.
Last year our government renewed its advise to store food and water for
two weeks. I immediately re-assigned my surplus body weight to civil defense
preparations. Fressen fuers Vaterland ! (= Gorging for the Country !)

In the real world of emergencies, your mileage may vary, of course.

> 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".

That's more a problem with the fellow humans than with technical docs.
Nothing is easy if you only dig deep enough into its details.

> > So it is not dumb user versus smart programmer but rather insider versus
> > newcommer.

> Yes, exactly.

And thus the "emergency mode" problem turns out to be about the need for
becomming an insider at an inappropriate moment of time.
When you need a skilled friend, then technical documentation will hardly
be able to serve as a substitute.

Have a nice day :)

Thomas

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