[net.news.group] net.doc

gda@creare.uucp (Gray Abbott) (10/16/85)

	I vote for net.doc .  The first item I would like to see is a Guide
	to Unix Documentation.  The most frustrating thing about looking for
	something in the Unix Programmers Guide is you usually have to know
	its *name* in order to find it. The second most frustrating thing is
	that there are no *examples* which make usage clear (how about an
	Examples Manual?). The third worst thing is that not all of the
	pointers (SEE ALSO) that should be there *are* there.

	And how about some more clever program than "man" to help
	find things ??

			Gray Abbott
			Creare Inc.
			Hanover, NH
			{...dartvax!creare!gda}

fair@ucbarpa.BERKELEY.EDU (Erik E. &) (10/17/85)

In article <381@creare.uucp> gda@creare.uucp (Gray Abbott) writes:
>
>	I vote for net.doc .  The first item I would like to see is a Guide
>	to Unix Documentation.  The most frustrating thing about looking for
>	something in the Unix Programmers Guide is you usually have to know
>	its *name* in order to find it. The second most frustrating thing is
>	that there are no *examples* which make usage clear (how about an
>	Examples Manual?). The third worst thing is that not all of the
>	pointers (SEE ALSO) that should be there *are* there.

I await with breathless anticipation your proposal for finding
competant technical writers who are willing to give away for free the
fruits of their labors.

What people haven't gotten through their heads yet is that creating a
newsgroup only creates a forum for discussion. IT DOES NOT GUARANTEE
DISCUSSION!

Even if there is discussion, there is no guarantee that it will be
`worthwhile' for any arbitrary definition of `worthwhile'. I cite
net.bizzare as perfect example of this.

	welcome to the real world,

	Erik E. Fair	ucbvax!fair	fair@ucbarpa.BERKELEY.EDU

dave@lsuc.UUCP (David Sherman) (10/18/85)

People are suggesting that we have a net.doc for every
UNIX neophyte to be able to use to ask questions to the net.

Please, NO NO NO NO NO!
We already have the right newsgroup for this - net.unix.
It's a matter of using it PROPERLY.

Most questions you have can be answered by someone relatively
close to you, and should not be sent around the world or even
the continent. Netnews is a scarce resource, and if people
start asking all kinds of questions which someone on their
site can answer, we'll be swamped.

What I do when I have a simple question is one of the following,
in progression:
	- ask a local person who's likely to know the answer
	- post to net.unix or net.unix-wizards WITH DISTRIBUTION
	  LIMITED TO MY CITY. If you're on a large machine,
	  you may be able to limit this further, to your machine,
	  or perhaps to your organization.
	- if the above two fail, and the question therefore appears
	  to be non-trivial, I'll consider posting to the net.

Dave Sherman
The Law Society of Upper Canada
Toronto
-- 
{  ihnp4!utzoo  pesnta  utcs  hcr  decvax!utcsri  }  !lsuc!dave

earlw@pesnta.UUCP (20) (10/19/85)

In article <381@creare.uucp> gda@creare.uucp (Gray Abbott) writes:
>
>	...
>	The second most frustrating thing is
>	that there are no *examples* which make usage clear (how about an
>	Examples Manual?). 
>	...

This is what Unix documentation needs desperately.  Just a one page example 
for each section 2 and 3 function would be a great help for most people.

peter@graffiti.UUCP (Peter da Silva) (10/20/85)

> 
> 	I vote for net.doc .  The first item I would like to see is a Guide
> 	to Unix Documentation...
> ... frustration about not being able to find things in the manual...

The Berkeley manual has a keyword-in-context index that is *extremely* useful.
The new AT&T manuals not only don't have that but they aren't even organised
into the right sections any more... I remember a Berkeley program called
"apropos" that looked up stuff in the KWIK index. Does it still exist?

nonh@utzoo.UUCP (Chris Robertson) (10/20/85)

This is another vote for mod.doc, especially for examples of usage.
I even have a first article to contribute -- a little C program showing
how to use the most common time routines, plus a short commentary on them.

Some have said we don't need mod.doc because we have net.unix, but I perceive
net.unix as for informal Q&A -- mod.doc contributions should be more
formally presented, checked out, and (with any luck) more complete
than the rambling discussions of net.unix.

If no one else desperately wants to do it, I will moderate the group if it's
formed.  My Unix expertise is that of competent user with C and system admin
experience (plus I am a vi and shell wizard, she confided modestly), and
I am a pretty decent technical writer.  How about a wizard volunteer to
check kernal etc. stuff I am shaky on?

--chris

sra@oddjob.UUCP (Scott R. Anderson) (10/23/85)

In article <327@graffiti.UUCP> peter@graffiti.UUCP (Peter da Silva) writes:
>
>The Berkeley manual has a keyword-in-context index that is *extremely* useful.
>The new AT&T manuals not only don't have that but they aren't even organised
>into the right sections any more... I remember a Berkeley program called
>"apropos" that looked up stuff in the KWIK index. Does it still exist?

It still exists in the standard Berkeley distribution; it has been removed
from the Sun release, as it is a synonym for "man -k".  The "whatis" command
uses the same data base, but only keys on the command name; it is essentially
a quick "man".

I agree with Peter that "man -k" is extremely useful; much more useful than
a VMS-style "help" command, which depends on a command name's ability to
convey the gist of the command's function (which, of course, would not work
with UNIX command names, and often does not with VMS command names). It also
requires a user to sift through a large number of names (~100) to find what
they want.  What would be more useful, I think, is something like the "how"
command posted by Bob Ware about a year ago, where commands are functionally
and hierarchically organized and selected.  It can be used when you know
what you want to do, but not "how" to do it.

					Scott Anderson
					ihnp4!oddjob!kaos!sra

peter@yetti.UUCP (Runge) (10/26/85)

> I agree with Peter that "man -k" is extremely useful; much more useful than
> a VMS-style "help" command, which depends on a command name's ability to
> convey the gist of the command's function (which, of course, would not work
> with UNIX command names, and often does not with VMS command names). 

There's a lot of unintentional humor in this comparison.  The percentage of
meaningful VMS commands relative to the total set is far higher than for
UNIX (the only meaningful Unix command I can remember off-hand is yes :-)),
and man -k is notorious for its inability to find anything appropriate.

VMS Help has a lot of faults (particularly if you just slap what Digital
provides on your system without doing some common-sense deletions and
additions to cover the local environment) but at least on VMS, I can work
effectively without a bookshelf full of manuals; my employer won't buy
me a set, but the point is: I couldn't justify it anyway -- the stuff I need
is almost all online. On VMS, self-instruction through the HELP facility is
a meaningful and feasible activity. On Unix, the thought of trying to learn
how to do things by reading man files seems ludicrous (at least for ordinary
mortals). For one thing, on our 780, asking for a man file to be
retrieved and formatted is something you do before leaving your office for
a coffee or a washroom break. When you get back, it will probably be waiting
for you - not the one you actually needed, mind you; it wasn't "refer"
that had the %codes, it was "addbib"! But surely, you could use another
cup of coffee?
-- 

   Peter H. Roosen-Runge, Department of Computer Science, York University
                          Toronto M3J 1P3 , Ontario, Canada
_____________________________________________________________________________
"Eccles, is the ship sinking?"   "Only below the sea."  
"We must try to save the ship -- help me get it into the lifeboat."
_____________________________________________________________________________

tp@ndm20 (10/28/85)

Actually,  there  are 2  groups that,  taken together,  cover all the
proposed uses of net.doc.   For  questions about  unix, use net.unix.
If you have some  documentation that  would be  valuable to somebody,
post it to net.sources.  net.sources IS the appropriate place to post
documentation.    If the  volume becomes  large, then net.sources.doc
will  be  created, as  per the  normal net  procedures.   There is at
present  no  demonstrated  need.    Prove  me  wrong  (PLEASE!)    by
generating some volume in net.sources.  Discussions about what should
be posted should be in net.unix or net.unix-wizards  (for kernel type
things).    If  a sufficient  volume ensues,  then we  can talk about
net.sources.doc, and discussion can  be moved  there (though net.unix
would probably STILL be the best place for such discussion).  

Getting  groups  created  under  those  circumstances  is quite easy.
Doing as you are trying, with no demonstrated  volume, is impossible.
You might as  well quit  asking because  it just  doesn't happen that
way, no matter what the perceived usefulness of  the group.   This is
because most groups created without demonstrated need (cf.
mod.general) turn into empty  forums.   Everybody is  waiting to read
the wonderful  articles that  should be  posted there,  and nobody is
writing them.  Groups need to  be created  when there  are people who
want to post something, not when people want to read something.

Terry Poot
Nathan D. Maier Consulting Engineers
(214)739-4741
Usenet: ...!{allegra|ihnp4}!convex!smu!ndm20!tp
CSNET:  ndm20!tp@smu
ARPA:   ndm20!tp%smu@csnet-relay.ARPA

sra@oddjob.UUCP (Scott R. Anderson) (10/29/85)

In article <267@yetti.UUCP> peter@yetti.UUCP (Runge) writes:
>> I agree with Peter that "man -k" is extremely useful; much more useful than
>> a VMS-style "help" command, which depends on a command name's ability to
>> convey the gist of the command's function (which, of course, would not work
>> with UNIX command names, and often does not with VMS command names). 
>
>There's a lot of unintentional humor in this comparison.  The percentage of
>meaningful VMS commands relative to the total set is far higher than for
>UNIX (the only meaningful Unix command I can remember off-hand is yes :-)),

I do not deny that VMS command names are generally more meaningful than
UNIX command names, but that doesn't make help easier to use than man -k.
They are both keyword-oriented, but with help you have a user trying to
sift through a screen-full of keywords (some of which ARE meaningless in
their generality -- set and analyze come to mind) to possibly find the
one you are thinking of.  With man -k, the program does the sifting
for you, and through a much larger data base, the command descriptions.
The latter are going to have a better set of meaningful keywords (assuming
they are well-written) since they are not limited to being one keyword
per command.

>and man -k is notorious for its inability to find anything appropriate.

How often does your brain flash "Nothing appropriate" when you are using
VMS help? (:-)

>For one thing, on our 780, asking for a man file to be
>retrieved and formatted is something you do before leaving your office for
>a coffee or a washroom break.

Get your system manager to set up the 'cat' version of the manuals.  They
take up about 3 MB of disk space, but are much faster than the unformatted
versions.

					Scott Anderson
					ihnp4!oddjob!kaos!sra

levy@ttrdc.UUCP (Daniel R. Levy) (10/30/85)

In article <532@ttrdc.UUCP>, levy@ttrdc.UUCP (that's me) writes:
>
>Yeah?  How about raw terminal interfaces, for an example.  On Unix, do a
>"man 4 tty" (BSD) or "man 7 tty" (USG) [yeah I know it's in the admin
>section but at least it's there].  Now, attempt to get similar online info

I owe the net a correction.  That section for USG is termio, not tty, in the
administrator's manual.  (I am looking now at a Sys5 manual.  I was posting
on such a machine too so shame on me for not looking at those "easily ac-
cessible" :-) online man pages!)  Still my main point stands.
-- 
 -------------------------------    Disclaimer:  The views contained herein are
|       dan levy | yvel nad      |  my own and are not at all those of my em-
|         an engihacker @        |  ployer or the administrator of any computer
| at&t computer systems division |  upon which I may hack.
|        skokie, illinois        |
 --------------------------------   Path: ..!ihnp4!ttrdc!levy

peter@graffiti.UUCP (Peter da Silva) (10/31/85)

> additions to cover the local environment) but at least on VMS, I can work
> effectively without a bookshelf full of manuals; my employer won't buy
> me a set, but the point is: I couldn't justify it anyway -- the stuff I need
> is almost all online. On VMS, self-instruction through the HELP facility is

I can also work without a bookshelf full of manuals. I only need 2: the UNIX
Programmer's Manual and the Users Guide. When I was working on RSX I needed
all 6.5 volumes all the time, and VMS doesn't seem to be any better.

> mortals). For one thing, on our 780, asking for a man file to be
> retrieved and formatted is something you do before leaving your office for
> a coffee or a washroom break. When you get back, it will probably be waiting

So format all the man files ahead of time & archive off the unformatted
version like everyone else does. Then man becomes a variant of cat/more.

> _____________________________________________________________________________
> "Eccles, is the ship sinking?"   "Only below the sea."  
> "We must try to save the ship -- help me get it into the lifeboat."
> _____________________________________________________________________________

You rotten swines, you deaded me!

(exits left. waits for applause. not a sausage)
-- 
Name: Peter da Silva
Graphic: `-_-'
UUCP: ...!shell!{graffiti,baylor}!peter
IAEF: ...!kitty!baylor!peter

iwm@icdoc.UUCP (Ian Moor) (11/16/85)

In article <854@lsuc.UUCP> dave@lsuc.UUCP (David Sherman) writes:
>People are suggesting that we have a net.doc for every
>UNIX neophyte to be able to use to ask questions to the net.
>Most questions you have can be answered by someone relatively
>close to you, and should not be sent around the world or even
>the continent. Netnews is a scarce resource, and if people
>What I do when I have a simple question is one of the following,
>in progression:
>	- ask a local person who's likely to know the answer

I have shared offices at different times with two people in this
position and I began to wonder how they got any work done, there
was a stream of people all day long:
 "when I type send foo!baa it says event not found ..."
I have got to know VMS more than most people round here and I 
am able to tell people with questions to type HELP or point to the manuals
which have examples of each command. I find unix has two problems
working out what command to use, and how to do anthing not explained
explicitly in the man page. 
net.docs could have as a starter the notes written for students starting
to use unix. 

-- 
Ian W Moor
  UUCP: seismo!mcvax!ukc!icdoc!iwm
  ARPA: iwm%icdoc@ucl                        
           
 Department of Computing   Whereat a great and far-off voice was heard, saying,
 Imperial College.         Poop-poop-poopy, and it was even so; and the days
 180 Queensgate            of Poopy Panda were long in the land.
 London SW7 Uk.         

pdg@ihdev.UUCP (P. D. Guthrie) (11/18/85)

In article <264@ivax.icdoc.UUCP> iwm@icdoc.UUCP (Ian Moor) writes:
>In article <854@lsuc.UUCP> dave@lsuc.UUCP (David Sherman) writes:
>>People are suggesting that we have a net.doc for every
>>UNIX neophyte to be able to use to ask questions to the net.
>>Most questions you have can be answered by someone relatively
>>close to you, and should not be sent around the world or even
>>the continent. Netnews is a scarce resource, and if people
>>What I do when I have a simple question is one of the following,
>>in progression:
>>	- ask a local person who's likely to know the answer
>
Quite right!!
>net.docs could have as a starter the notes written for students starting
>to use unix. 
>
Yes.  I believe the whole idea behind net.docs is NOT to compete with
net.unix, or your local guru, but to provide a distinct place for
DOCUMENTATION to be posted, much as in the way that sources are posted
to net.sources.  I think that every site, especially universities, have
collected over the years documentation on every aspect of computing,
from "How to install new device drivers on UNIX" to "How to boot your
IBM PC".  Now, if we had a place to post these, then in immitation of
net.sources, those people that see a use for these papers could save
them.  I actually think that mod.docs would be a better idea though, 
just to keep the amount of illiterate trash down (no flames about my
spelling or grammar - this is a posting *not* a published paper).  I
remember seeing a volunteer to be moderator, so if he would step forward
again, and if net.powers-that-be will not create mod.docs, why not have
a mailing list, so those poor objecting whiners need not be subjected to
having to hit the 'n' key when the create newsgroup message comes
around.

					Paul Guthrie
					ihnp4!ihdev!pdg

chris@globetek.UUCP (Chris Robertson) (11/20/85)

In article <404@ihdev.UUCP> pdg@ihdev.UUCP (55224-P. D. Guthrie) writes:
> ...I remember seeing a volunteer to be moderator [of mod.docs], so if he
> would step forward again, and if net.powers-that-be will not create mod.docs,
> why not have a mailing list...

I once again volunteer my services as moderator for mod.docs, or as
co-ordinator for a mailing list.  All in favour of a mailing list, send
me mail, and send me docs!

Christine Robertson  {linus, ihnp4, decvax}!utzoo!globetek!chris

ron@brl-sem.ARPA (Ron Natalie <ron>) (11/27/85)

> I once again volunteer my services as moderator for mod.docs, or as
> co-ordinator for a mailing list.  All in favour of a mailing list, send
> me mail, and send me docs!
> 

Sorry for the delay, I do have the votes that were called for.  The
support was near unanimous for a moderate mod.docs group.  I intend
to set up the group as described, but I have been hampered by some
problems with the serial lines on BRL-SEM.  This group will be created
next week.

-Ron