Re: Internet Architecture Project - PLEASE HELP

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

"Anthony" <anthony_colello -at- yahoo -dot- com> wrote 

> Hello Everyone,
> 
> I took a job for a large insurance provider about two
> weeks ago and the primary focus of the job is
> documenting what they refer to as their "Internet
> Architecture."
> 
> What they want is a technical reference manual for
> programmers and developers which documents their
> system of servers, mainframes, routers, ATM switches,
> applications, etc.  Further they want this manual to
> be documented down to the "file level" of detail and
> have a variety of diagrams and tables in addition to
> the usual narrative content.  The system is used
> primarily for quoting, managing, and underwriting
> insurance policies.
> 
> Can anyone help me with ideas of how to attack this
> monster?

Ah, fun! Sounds like an ops manuals. Done a few in my time. Mostly just a big
collection of data (well organized of course). You'll never get all the info
from the engineers. You'll have to scour it from the network yourself. 

1. You need a network diagram. If they don't have one, you'll need to put one
together. Plenty of books and resources on this. Get a copy of Visio 2000.
Start diagramming. 

2. Scan your internal network range using a tool like SuperScan from
Foundstone. That will determine what machines are there and what aren't. It can
also scan for open ports. If your company has any security on the network
(which they probably don't) you'll set off the IDSs. But that will at least
show them that you know what you're doing (sort of). 

3. You need access to all those servers. An account with at least read access
to everything on the servers.

4. You need a server map - what server provides what services. How are those
services configured. That means getting configuration information on each
software package installed on the system. 

5. You need directory maps. On windows systems this is easily accomplished
using the dir /s > filename.txt command. It will pipe a complete map of the
directory to the text file "filename.txt" Perform this on each drive, on each
server. UNIX boxes have a similar command.  Once you get the maps, you'll need
to sort out what are OS files and what are program files and what are the data
files (or user files). This is pretty straightforward...if you know Windows and
UNIX. If not, pray for the kindness of SMEs. 

6. You'll need to walk through the MIBs on the switches and grab all the
configuration info. I recommend a MIB walking tool like GETif  (More info:
http://www.wtcs.org/snmp4tpc/testing.htm). Get a read only community string
from the engineers. If they look at you funny and ask why - you're doing good.
They'll probably be amazed to see a tech writer knows what an SNMP community
string is. 

7. Dig your ISPs DNS servers if you need maps of systems. This is really fun.
You'll find out all sorts of fun data on your firm. You can get a DIG program
lots of places on the Internet. The UNIX versions work better, but there are
some nice Windoze versions. See www.samspade.com for a good Windows digging
tool. 

8. Find their database systems. Get data models out of them. Get a copy of
ERwin. If they use SQL Server you're in luck. it comes with a simple modeling
tool built in. Have it generate models of the databases. 

My recommendation is to break this doc in to these categories:

Network Topology
Network Routing Devices
Name Servers
Network Services Servers (this includes DNS servers, WINS servers, etc.)
File Servers
Mainframes
Internet Servers
Web Site Architecture 
Database Models
Data Dictionaries

Here is what you don't waste time on:

Templates
Style guide
Any kind of methodology
Sign-off sheets
Fonts, commas, etc. 
Documentation repositories. (Make a folder on a server, save your files there.
Doc repository project finished.)
Tools. This kind of technical docs should be done in Word - a format that is
easily portable and can be sent to any engineer in the company.

You are lucky, Anthony. You have a purely technical, technical writing project.
My kind of job. Complex, geeky, full of whirring servers and blinking switches.
You don't have to worry about the insidious one-off crap that consumes user doc
writers. You can focus all your energy on gathering data, learning about
technologies, and working with engineers - the fun stuff.

This is the type of work where you learn tons of cool stuff that will benefit
you immensely in other jobs down the road. I did the exact job you describe in
1995 for a Microsoft group. It was the single best contract job I have ever
had. I learned more about Perl scripting, SQL Server, Windows NT, and web
architecture in 9 months on that contract then I would have learned in 9 years
through classes. It is what allowed me to start my own company.

Get crackin' dude. Impress the hell out of them by showing them a ops manual
that is busting at the seams with detailed technical data. And if you get stuck
- you can always hire me. :-) 

Andrew Plato 

<<Shameless self advertising>>
Blow money at my store: http:\www.cafepress.comAnitianStuff

__________________________________________________
Do You Yahoo!?
Yahoo! Tax Center - online filing with TurboTax
http://taxes.yahoo.com/

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.