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(a)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