>
>
> >* It's too hard to find stuff in it. Usually, those complaining are
> > looking for command-line flags, which are fairly buried in most info
> > documents. Those complaining are also usually unaware of info
> > features such as the easy-to-access index and the ability to search
> > the whole document by regexp.
>
> There's the nutshell, the information you use the most often needs
> to be readily available, most of the info pages I've read in the
> last few days have been heavily laden with theory, and concept,
> not a command line refresher... especially for those badly borked
> commands without --help. Perhaps info pages need an "executive
> summary" of all commands and methods.
>
Well, writers who know the material and how to write documentation would help.
Unfortunately, most programmers don't write good documentation.
Take gcc as an example; even the help output os too voluminous for most needs.
IBM's C/C++ compiler (for OS/2) has 13 manuals, including "Read Me First"
which describes how to install and configure it and related matters, tutorials
and reference manuals. Some of these come on paper too. All the manuals are in
thre softcopy formats; postscript (I can view that on Linux), OS/2 inf files,
and BookManager files.
To be fair, IBM's package contains more than a C/C++ compiler. However, it's
far to say that gcc needs, in separate documents,
Installation & configuration. Audience - sysadmin
Getting started. Audience - beginners
C Reference Audience - programmers
C++ Reference Audience - programmers
Programmers guide Audience - programmers.
This last covers, in detail, how to use the compiler and related tools, and
how to code C and C++ programs. The Getting Started document would cover the
same kind of material, but in much less detail; it would be enough to get
users writing simple programs, compiling them and running the debugger.
On OS/2, you'd find the manuals in a folder on the desktop, or in a folder in
a folder on the desktop (I don't recall exactly, the name, but there's a
clearly-identifiable folder on the desktop containing OS/2 manuals). It's hard
to explain why the folder on the desktop is easier to use than the thing at
the bottom of the screen with a help browser on it, but I find it so.
_______________________________________________
Redhat-devel-list mailing list
[EMAIL PROTECTED]
https://listman.redhat.com/mailman/listinfo/redhat-devel-list
