[wplug] documenting network layout

[Christopher DeMarco]

On Sat, Nov 20, 2004 at 02:48:26PM -0500, Carl Benedict wrote:

> http://www.gnome.org/projects/dia/

Dia is *very* good.


As for the approach, I would come out in  *opposition* to any standard
or "best practice"  for documenting your  network setup.  Use your own
words and  your  own   voice to  describe    what's what and   how  it
frobnosticates, and you'll reach   your reader[s] much better  than if
you template the process to death.  I've never worked in the sciences,
but in the liberal  arts (don't laugh) there   are style guides  which
specify how  "canonical"  English is to   be written, and publications
have style guides  to which  submitted  writing must conform,  but the
structure and  form  of the document   is *not* specified, as  it's an
artifact of the individual mind which produces it.

What to document?  Think like a journalist:

WHO  should read your  document?  WHO are   the users of the computing
facilities?  WHO  are  the other  administrators?   WHO maintains  the
equiment in case of failures, new purchases and upgrades?  WHO are the
different  classes of users?  WHO  is  involved in the administrative,
financial, and legal  aspects of the  network?   WHO are the  external
people,  groups,  departments, colleges,  universities, commercial and
government entities, networks and others  with whom you interact?  WHO
can you call for help when things FUBAR?

WHAT things   exists in the  network?  WHAT  different  OSes, software
packages,   hardware  types and vendors do   you  have?  WHAT discrete
networks do you have?  WHAT data stores do you have?  WHAT peripherals
(printers,        scanners, flux-panning gonadotropic  sturmunddrangen
thudwhackers, etc) do  you   have?  WHAT policies,   restrictions  and
charters  pertain  to your     systems?  WHAT  information,   physical
resources and access   are sensitive  or restricted?  WHAT   different
classes of security exist?

WHEN  are  the resources  in  use?   WHEN  are  there any  significant
increases or decreases in  the type  and/or quantity  of  usage?  WHEN
were   significant hardware or configuration   changes made?  WHEN are
things  planned to change?  WHEN  do you think current conditions will
worsen or better to  the  point that e.g.  new   backup tapes will  be
required?   WHEN do  periodic  events  like backups, security  audits,
budget requests, maintenance windows, support contracts, etc. happen?

WHERE are the  various pieces of your  network live?   WHERE do cables
run within buildings and rooms?  WHERE  are the tools kept?  WHERE are
the backups stored?    WHERE are spare parts   kept?   WHERE are  your
vendors?   WHERE  is your  boss?   From WHERE    do your  remote users
connect?  From WHERE does  your incoming traffic  come?  To WHERE does
your outgoing traffic go?  WHERE do you keep secure or sensitive
information?  

WHY do  you have these   various  systems?  WHY does your   department
exist?   WHY  does  your job  exist?    WHY  are  certain policies and
procedures in  place?  WHY haven't certain  systems been upgraded past
their current levels?

HOW do  you  put together simple  tasks to  perform common  high-level
duties, such as adding a new node to a cluster or flushing a web proxy
cache?  HOW  do the various sub-systems  fit together?  HOW  do things
typically fail, and HOW  do you know about failures?   HOW do you find
additional information beyond  what  you've documented?  HOW  do  your
systems talk  to each  other?  HOW  do you  get  more money,  or  more
resources?


Do *not* underestimate the WHO and WHY  questions - they're the reason
you have computing facilities in the first  place.  Vendor docs can do
much of the heavy lifting to get the  new guys through the day-to-day;
the big   picture however is the story   of what people  *do* with the
systems  and how you  can help them with their  work.   The paradox is
that l?users are the bane of, yet the  reason for, your existence - so
documenting the impact of  society, economics, politics  and academics
on your systems will be an invaluable aid to the newcomers.


-- 
% You are in a maze of twisty passages, all alike.
Christopher DeMarco <cdemarco at fastmail.fm>          
PGP public key ID 0x2E76CF5C @ pgp.mit.edu
+6012 232 2106
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://penguin.wplug.org/pipermail/wplug/attachments/20041121/e4e3b469/attachment.bin