Re: Do have programs have poor documentation?
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
Reply to: