Subject: Linux-Activists - Channel DOC digest. 92-11-17-22:28
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Fri, 18 Dec 1992 08:33:39 +0200

Topics:
	 feedback re: outline of docs
	 Chris cross

----------------------------------------------------------------------

From: "Vincent D. Skahan" <[email-masked]>
Subject: feedback re: outline of docs
Date: Thu, 17 Dec 1992 23:28:03 +0200

I know I'm getting into this late, so please interpret what I say
as my opinions only and you're obviously free to take it or leave it
as you see fit since it's your show :-)

I beta-tested the Documentation set for Apollo Domain/OS when we served
as a beta for the software also and came up with lots of ideas regarding
how to make documentation readable for the people who needed it, yet
not flood people with docs they'd NEVER use as part of a VMS-like wall
of manuals and docs.

What we came up with as a recommendation was to have something like
the layout you have, but with drop-in chapters that you'd either get
or not get.  The intent was to have something like the VMS wall of books,
but with a more unified look...something like a big 3-ring binder with
a bunch of dividers in it, but only some of the chapters included.

Something like this would also match up with the SLS philosophy of
a menu where you pick one from column-A and two from column-B.  Think
of it as the SLS of documentation :-)

Want all the docs except the networking stuff...no problem.
Want just the sys-admin docs...cool.
Want just the X-books...ok.

Also, I think maybe you're starting with too ambitious a goal, even
though I like the long-term goal and would love to have a unified set
of unix docs including care/feeding/use/administration...someday.

I'd like to see an experienced-person's guide to linux with JUST the 
linux-isms first, with all the rookie-user sections just pointing to 
existing books you can buy.  There's a number of fine FAQs about what
books and anon-ftp-able docs out there that should be referenced 
rather than reinventing the wheel at this time at least.

[...you mentioned that you want to point emacs stuff to the O'Reilly
	and Assoc book.  I think you should extend that to say 'get the
	OR+A NFS book for NFS, the OR+A X11R5 for that, the various shell
	programming books for that, etc...]

If the people who were going to reinvent the wheel spent all their time
just documented the linux-isms, we'd have some incredible documentation
about linux itself.

Anyway, back to the original feedback...

> ** 1.2 Before you get started....
> 	Will cover all of those preliminary worries that you get before
> 	putting Linux on your machine... "Will it coexist with DOS?" etc.
> 	I'll also talk about the FAQ's and various on-line docs here. The FAQ
> 	will still be needed to deal with obscure individual problems, but
> 	for the most part this guide will be able to cover everything needed
> 	to setup a Linux system.

in other words, a Damn-frequently asked questions section :-)

> ** 2.1 Getting Linux via FTP
> 	This will explain where to go and what files to get for the SLS
> 	release, and what to do with those files. The details of how to use
> 	FTP will be left for an Appendix, so that the FTP information can
> 	be used more generally for getting ANYTHING. 

there is an existing FAQ in alt.something (I forget) that includes a
wonderful tutorial of how to use ftp. If I find it in the mess of my
home directory, I'll forward it via mail.

> ** 2.2 Getting Linux from BBS's
> 	I need help on this part, since I've never done it before. :) 
> 	Most of the info is there in the FAQ, but I don't know exactly
> 	what files are there. Is SLS even on BBS's? I've never checked.

yes, it's on many BBS and is also available from usenet->fidonet
means too...see the linux bbs periodic posting for details.
I get my SLS via zmodem from one of the bbs's on the list.

> ** 2.3 Getting Linux via Snail Mail
> 	Will tell how to get SLS from Peter via mail, and will also list
> 	some of the other people who are willing to distribute Linux on 
> 	floppy via mail. Can someone send me the address of the guy who was
> 	getting the list of SLS by-mail distributors?

for what it's worth, it is considered by many to be extremely un-neighborly
to grab the 40MB of SLS (maybe 50+MB uuencoded/split) via mail since such
requests significantly load up all the systems in-between.  It's also (IMHO)
a very dumb way to get the whole thing since it's soooooooo big, though I
guess I can understand wanting to get a few pieces that way.

> **** 3.1.1.1 Killing your DOS partition
> 	Using DOS's fdisk to kill your current DOS setup. Optional for
> 	those who have a clean drive.

you can use linux's fdisk to nuke it...I'm pretty sure that's what I did.

> **** 3.1.2.1 Running Linux fdisk
> 	Talk about running fdisk to make the partitions decided upon above.
> 	I need to know the differences for people with SCSI drives and more
> 	than one drive in the machine.

I have 2 hard disks with linux on the 2nd disk, so I can answer I think.

the default is for 'fdisk' to actually do a 'fdisk /dev/hda'.
if you want to do the second disk instead, do 'fdisk /dev/hdb'.

> ** 4.3 Poking around the system
> 	Will make comparisons with DOS where appropriate; however I won't
> 	assume knowledge of DOS. Will explain all the ins and outs of 
> 	files, directories, permissions, owners, processes, etc.

please don't acknowledge DOS's existance.
you're documenting Linux, not DOS so just document linux.

> ** 4.4 Editing files 
> 	Quick use of vi. Not too rough, I've been able to teach a lot of
> 	new users vi in a few minutes. It takes some getting used to. 
> 	If there are objections I can cover joe instead, but I think only
> 	vi will be found in all releases. There will be multiple subsections
> 	under this one, I just haven't leafed them all out yet.

there are a number of fine vi tutorials floating about periodically
in comp.editors so just get the ok from the author(s) to include them
and you'll be done (or point them to where they can be gotten from).

> *** 5.1.3 Other /etc configuration files
> 	Simple things like /etc/motd, /etc/issue, and so on. Will 
> 	explain briefly the uses of these files.

you might want to add care'n-feeding of things like e-mail,uucp,
and usenet news here or else refer them to another section for
those things (see further comments below)

One of the things that was in comp.unix.large (maybe...) within the
last year was that it would be a great aid to have EVERY command
have a consistent command-line option that printed out a string 
telling what the command did and what its version was...kind'a like
a 'whatis' database line embedded in each command.

> *** 5.1.4 Adding users
> 	Really quick intro to the /etc/passwd and /etc/group files,
> 	how to add a user by hand. System admins need to know how
> 	to manage users by hand, but we'll also talk about adduser
> 	scripts. BTW, what adduser script is distributed in SLS?

ummm... 'adduser' I think.
It's pretty good...adds them, creates their home, etc.

> *** 5.1.6 Basic security issues
> 	Simple topics on system security-- mostly common-sense stuff for 
> 	most of us, but not obvious to new system admins. How to protect
> 	passwords, 'correct' permissions of files, and so on.

like why to keep the encrypted passwords non-readable since 'crack' runs
so nicely :-( under linux.

> ** 6.2 Use of ps and kill 
> 	Managing processes, backgrounding jobs, and so on. A lot of this
> 	will be easier if we can guarantee that tcsh or bash will be
> 	available, but I will make sure to mention what items will only
> 	work under certain shells.

mention use of 'top' to do killing of processes by process id since
it does a fine job of insulating the user from learning kill.

> * 7.0 Other software installation and configuration
> 	Apart from the base system, we have things like TeX, X11, tcp/ip,
> 	and so on. I'd really like to (eventually) include info on setting
> 	up and configuring these packages for Linux. Everything above is
> 	based on a 'base system' setup; mostly just the things from
> 	the a, b, and c SLS disk sets. Since this is indeed the
> 	"Installation Guide" I'd like to talk about how to add these
> 	packages, both by hand and using SLS's nifty package management stuff.
> 	Then, I'd like to focus on setting up and configuring X, TeX,
> 	tcp/ip, emacs, and so on. 
> 

you might want to consider making this a 'linux networking' section
including:
	- serial i/o (modems, dumb terminals, uugetty, etc.)
	- uucp/mail
	- usenet news
	- tcp/ip-related goodies (telnet/ftp/rsh/NFS) not including
		X-related stuff

> * A.0 Appendices
> 	This will be information that can 'stand alone', for the most part--
> 	supplemental stuff that we can't do without.

how about 'how to find sources, how to use archie, why to read news.answers...'

> ** A.1 Common Problems and Solutions
> 	A lot stolen from the FAQ, but condensed, easier to read, more concise.
> 	I'm putting this last because the answers often depend on knowledge
> 	from all of the stuff above. Will refer to this section throughout
> 	the rest of the book; i.e. "If ps doesn't work, see section A.1.2...".
> 	This is just to put all of the non-obvious stuff in one place, since
> 	(in theory) you shouldn't run into these problems if you've done
> 	everything correctly. Also makes it easier to reference rather than
> 	intertwining it with the rest of the text.

the one thing most sets of docs don't have is an integrated index that
can be searched on keywords...is that why you picked texinfo?

> ** A.2 How to use FTP
> 	Short tutorial on using FTP to transfer files between machines.
> 	This will center on the UNIX-style FTP client; Macs and other
> 	platforms with different FTP clients will also be touched on, but
> 	the ideas are the same. This is being put in an appendix to get it
> 	out of the way of the main text-- it's too distracting.

again, already done in alt.something...see the news.answers archives on
pit-manager.mit.edu.  I think it was a FAQ about mailing lists but I can't
remember for sure.

> PLEASE send me comments on this! If you mail comments to the mailing list,
> please Cc them to me so I don't have to wait on for the digests... I'd like
> to get started as soon as possible. This is far from complete.

but it's darn nice so far!

> Please note that I especially need help on info for SCSI drives and 
> using multiple drives, getting Linux from BBS's, and the filesystem layout
> that we should suggest in this document. And, if you're interested in
> writing any of the above sections, please let me know ASAP! 

by filesystem layout, I'm hoping you mean the directory tree structure
that SLS has a result of the flame wars way-back-when...

sure, I might be able to help somewhat with the uucp/mail/news stuff
and by proofreading some stuff...let me know via mail.
  
  ---------   Vince Skahan   ----- [email-masked] ------- 
	The weather ??? It's Seattle.  It's winter.  It's raining.

------------------------------

From: [email-masked] (Lars Aronsson)
Subject: Chris cross
Date: Fri, 18 Dec 1992 03:01:26 +0200

Instead of planning and outlining a lot, I have actually been writing.

I have gathered some notes from the top of my head and added info from
man pages. The result is a first version of a LINUX cross reference.
The format is all ASCII. You can get your copy by anonymous FTP to
ftp.lysator.liu.se, in directory /pub/linux/lysator. I keep the
copyright, but you can distribute according to GPL, just like LINUX.

In my mind, this is not ready for the general public in comp.os.linux
yet, so I am only announcing it here on the DOC channel, as a help for
documentation writers. If you have a boring Christmas, at least you
will have something to read. I expect my mailbox to be full of
complaints when I get back in early January. Good Yule all!

------------------------------

End of DOC Digest
*****************
-------