I have a dream, of a help/manual/doc system, which is simple to use?

[Malcolm Kay]

On Sat, 21 Feb 2004 22:28, Niel wrote:
> Written 21st january 2004.
>
> I have a dream, of a help/manual/doc system, which is simple to use?
>
> I have a dream, of a help/manual/doc system, which is simple, and yet
> comprehensive to use.
>
> When I need help to some question, when using freebsd, I often get very
> confused, and cannot find out how to do it.
>
> Often I find some manual, but then pages and pages start scrolling past my
> eyes, and soon I am very confused, and my brain looses track of what it
> trying to do. Often there is some tecnical abbreviations mixed into the
> explanation, which we do not know at all, what is!
>
> There exist a very comprehensive documentation for freebsd, man, faq etc.
> So far, that is very good. Leave it as it is. That is okay for later
> reading.
>
> But what I am searching for, is very short manuals for every topic and
> program. How to install it, where the files are sitting, how to set-up.
> Just a very simple example, for just to get a basic program running. And
> also a very basic example for using the program, so you at least are
> getting it up and running. Then you can later experiment with more
> complicated items og the programs.
>
> I am also in search for a very big handbook, with cross reference word, for
> ALL words. So you can find out, where to look, every thinkable word you
> might meet, when installing and using freebsd.
>
> I am a newbee, and I cannot simply remember, where I last read -or found a
> subject. I mean, most endusers simply do not have such a glue brain, that
> they can remember. (Many times they simply tells themselves: "Let me stay
> with windows. That I am used to.)
>
> I have tried using linux red hat, caldera and suse, and I have now begun
> using FreeBSD, and I find it the best system so far, with the most easy
> help system. Nothing wrong with that.
>
> To sum up. Please simple manuals for all the some 6.000 programs, shell
> commands, etc, with lots of simple to understand examples, so one at least
> can get started.
>
> This is just a newbees hottest wish.
>
> Even Microsoft have not yet found out, how important above is. It is the
> alpha and omega, for using operating systems and programs, for ordinary
> people. ( I have even found the same problems in manuals for tv, video and
> so on. )
>
> I mean many people have difficulties just reading a simple explanation.
>
> It is okay, to make very sophisticated programs, but it is as important,
> that the enduser can find out, how to use it.
>
> And, please use simple English words. We enduser come from all parts of the
> world, and do not all have the English language as our native language. And
> please no humour! :-) If you live in Africa, you do not know American
> slang?
>
>
> Yes, I still have a dream .....    *smiling - positive*
>
> Regards,
>
> A freebsd "Grassroot", hoping to saw just a tiny seed in some smart
> programmers mind, so we can start begin really using UNIX type operating
> systems, instead og windows 98!   *serious - thinking - :-) *

I think you are looking for a computer that can read your mind.

In the meantime it is hard to imagine a help system that works better than the 
unix man pages. Admittedly there are some instances of missing man pages,
poorly written pages and pages not conforming to conventions -- but these
represent a very small fraction of the whole. Generally items can be found 
without too much irrelevant garbage to sift through as in Microsoft help systems.
(There is some very useful information hidden away in the Microsoft 
system but have not found out how to find it when it is required -- it only
ever pops up when looking for some totally unrelated information.)

As for the GNU info system, it is a little better the M$ but generally rather
cumbersome -- difficult to find the particular aspect you are looking for.
Better suited for tutorials than as a help reference.

Of course there are also things like KDE help, which states the obvious but in which 
you can't find the non-obvious because it is not there.

So rather than trying to invent a new approach with a new set of shortcomings
try enhancing the existing man pages by filling the gaps and rewriting where 
appropriate. I can appreciate validity of your remarks with respect to the impact
of American slang and humour on non-Americans. On the other hand it can be difficult
to distiguish between slang and idiomatic use of the language. I would prefer pages 
written in International English rather than American. But in regard to programming 
related pages I guess one has to admit that most programming languages are 
based on the American wriiten language rather than English.

For me the man pages make all other attempts at help systems look very Mickey Mouse
(with appologies to Disney).

Malcolm