Internet Architecture Project - PLEASE HELP?

Subject: Internet Architecture Project - PLEASE HELP?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 3 Apr 2002 09:10:56 -0500


Anthony Colello reports: <<... 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 clincher is that they have little more
than diagrams to start the project with. Most of the information is
supposed to be garnished by interviewing the programmers and developers.>>

Sounds like a very large project, and that the size, more than any inherent
complexity, is what's got you worried. The key to doing this right, with the
minimum stress on you, is to start simple: create an outline that lists all
the main things you need to document, then sit down with your manager and
establish a series of priorities and preliminary dates. A typical
date-priority combination might be something like "list all the servers on
the network, and the locations where I can find new servers that have been
added to the network, by May 1st".

Now you can start refinining each item in the list: for example, you might
have to break down "servers" into different categories (e.g., mail servers,
Web servers, firewalls) and start listing the resource people for each topic
in the list. Don't forget to list their availability, since that determines
whether your deadlines are feasible. If you know that a key resource person
for the server task will be away on vacation until May 1st, then obviously
the May 1st deadline is infeasible, and will have to be renegotiated. If you
know that another expert is only available to you on Fridays, then you need
to confirm that they'll be available to _you_ on Fridays.

Once you have a complete list of what and realistic guesses at when, you can
begin the actual work. There's an old cliche that "a journey of a thousand
miles begins with a single step", and that's exactly the way to approach
such large jobs. Focus on the short-term goals (putting one foot in front of
the other) rather than the destination (1000 miles... eek!) and the work
seems much less intimidating. So long as you can meet each milestone, you
won't have to worry much about the final destination, and that takes enough
pressure off you to make the work easier.

<<To make it even more interesting almost all of them [the experts] are
located out of state.>>

That's much less of a problem than it used to be assuming your company lets
you phone them long-distance, provides an e-mail account, and is willing to
consider letting you try technologies such as instant messaging or chat
rooms. The biggest issue is that you'll have a much harder time establishing
a personal relationship with each of these people, and the lack of such
relationships makes it harder to persuade them that you're not just another
annoyance placing demands on their time.

Start off early by introducing yourself, explaining your task, and trying to
find out how each person will prefer to work with you; some want e-mail,
while others may only accept telephone conversations. Find out what their
schedules are like so you can determine the best time to ask them questions.
In short, show some consideration for their needs so you can begin
persuading them to show some consideration for yours.

<<They also have no standards, style sheets, or document repository in place
to track any changes which might occur while I am documenting this.>>

Then you need to develop such a system; as is the case for the overall job,
you need to list the things that must be done and prioritize them. For
example, while we all recognize the importance of consistency and style
sheets, that's far less important than ensuring that you have a good review
process and some means of document control (the "document repository" you
mentioned).

If you can get the various experts on your side so that they're eager (or at
least willing) to help, you can make sure that they keep you up to date on
the most important things; if not, at least you can look at the file
modification dates in the repository to see which files have changed and
thus, which ones you need to revisit and bring up to date. You'll need some
way of determining the priority for such changes; for example, if the mail
server gets moved, it may be more important to document that immediately
than to complete the module of information you're currently working on.

One thing you should emphasize to your manager right from the start is that
it may simply be impossible for one person to produce a perfect description
of a changing architecture in the first draft. (In short: some jobs require
multiple writers to keep up with the volume of work being produced and the
volume of changes. Your job may too.) You'll both have to accept that the
result of all your writing will be something that is somewhat out of
date--the proverbial work in progress.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada

Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.



Follow-Ups:

Previous by Author: Centralized document management and decentralized document creati on?
Next by Author: Putting tips/notes within a numbered list?
Previous by Thread: RE: Putting tips/notes within a numbered list
Next by Thread: Re: Internet Architecture Project - PLEASE HELP?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads