[CentOS-docs] a general suggestion for all of the doc pages

Thu Oct 7 12:29:23 UTC 2010
Robert P. J. Day <rpjday at crashcourse.ca>

  generalizing somewhat from my earlier note about the "securing SSH"
page:

  http://wiki.centos.org/HowTos/Network/SecuringSSH

i don't know what level of intro a page like that should have but when
i've presented things like this to classes i've taught, or written
short online tutorials, the very first thing i document are the
packages involved.

  in this case, the first section might be something as simple as
showing the output from:

  $ rpm -qa "openssh*"

and, given the list of packages, a one-line description of what it's
for, which ones are necessary, and which ones simply add extra
functionality.

  and after that, i typically list every important file and directory
that will come into play at some point, again with a short
description.

  so for ssh, i would list the packages:

  * openssh
  * openssh-server
  * openssh-clients
  * openssh-askpass [optional]

then list what the reader will eventually have to work with:

  /etc/ssh/ssh_config
  /etc/ssh/sshd_config
  ~/.ssh

once the intro covers that sort of thing and maps out the terrain,
every subsequent section is almost trivial.  i'm just saying that that
approach has worked very well for me.

rday

-- 

========================================================================
Robert P. J. Day                               Waterloo, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================