TOC for Command Prompt Survival Guide

[Stuart Ellis]

On Fri, 2006-04-28 at 15:50 -0500, James McElhannon wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Hi All,
> 
> I wanted to propose the following TOC for the Command Prompt Survival
> Guide, one of the current Doc Ideas...
> 
> I would plan on submitting this document to the LDP, too.  Their
> equivalent doc is aging and is lite on details.
> 
> Please let me know your feedback.
> 
> - ---
> 
> There are 5 chapters shown below, with the sections numbered.  The
> Concepts chapter sets forth just enough theory to be able to use the
> commands below.
> 
> The Scenario chapter would put forth some common scenarios that people
> would be faced with.  The text would describe the usage of a set of
> commands to perform a task, cross referenced to the Commonly Used
> Commands section.
> 
> The Commonly Used Commands would not be a reproduction of the man pages,
> but would instead focus on the common usage of the command.
> 
> The Tools would section would be brief scripts to make some things
> easier.  I would expect that the details of this section would arise
> during the writing of the rest of the text.  Any redundant operations
> shown during the Scenarios would be candidates.
> 
> Introduction
> 1.	General introduction
> 
> Concepts:
> 1.	Shells
> 2.	Executables and Processes
> 3.	stdout, stderr, stdin
> 4.	Scripts
> 5.	Permissions
> 6.	Redirection and Pipes
> 7.	Bash prompt customization
> 
> Scenarios
> 1.      Handling zip/gz files
> 2.      Handling tar files
> ...     ...
> 
> Commonly Used Commands:
> 1.	basename
> 2.	bash
> 3.	bunzip
> 4.	bzip
> 5.	cd
> 6.	chgrp
> 7.	chmod
> 8.	chown
> 9.	clear
> 10.	cp
> 11.	cut
> 12.	echo
> 13.	expr
> 14.	find
> 15.	finger
> 16.	grep
> 17.	gunzip
> 18.	gzip
> 19.	head
> 20.	hostname
> 21.	info
> 22.	kill
> 23.	ln
> 24.	ls
> 25.	man
> 26.	mkdir
> 27.	more
> 28.	mv
> 29.	ping
> 30.	popd
> 31.	ps
> 32.	pushd
> 33.	rm
> 34.	rmdir
> 35.	rpm
> 36.	set
> 37.	stty
> 38.	su
> 39.	sudo
> 40.	tail
> 41.	tar
> 42.	test []
> 43.	traceroute
> 44.	uname
> 45.	wait
> 46.	wc
> 47.	where
> 48.	who am i
> 49.	whoami
> 
> Tools
> 1.	echodo
> ...     ...

This is a very general suggestion - it may be helpful to phrase the
"Concepts" headings in terms of tasks, since a new user may not strongly
associate the technical features with what they actually do. Some
features also relate to more one technology, e.g. a new user who has
just read about permissions may be puzzled by "permission denied"
messages unless there is at least a mention of SELinux.

This example is just off the top of my head:

Concepts:
1.	Understanding the Command-line Environment
2.	Running Commands
3.	How Logging Works
4.	Automating Commands as Scripts
5.	Understanding Linux Security
6.	Connecting Commands Together
7.	Discovering Commands
8.	Customizing Your Command-line Environment

Section 7 doesn't appear in your ToC - the idea is that if you explain
how to discover useful commands, you could focus on only describing a
small set of commands yourself, with a clean conscience, rather than
feeling obliged to select and cover many. Teach 'em how to fish :).

The GNOME desktop help browser in FC5 displays man and info
documentation, so the documentation for the hundreds of commands on the
system is accessible, but a new user may need pointers to how to locate
what they need. The apropos command also enables users to find the right
utility, once they are aware of it.

-- 

Stuart Ellis

stuart at elsn.org

Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

GPG key ID: 7098ABEA
GPG key fingerprint: 68B0 E291 FB19 C845 E60E  9569 292E E365 7098 ABEA
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060501/5642da54/attachment.sig>