Re: Operational Manuals - Please Help
This contract continues to get more interesting by the
day. Now we're going to develop an operational manual
from scratch for the company's architecture and its
various computer components.
Sounds like a meaty project. Good luck with it!
Next week I am going to go to the home office to
assess the situation on existing documentation. I'm
going to be speaking with several managers that run
various parts of the architecture.
What sorts of questions should I be asking these
managers when I am meeting with them?
For starters, consider this a mission to establish relationships with these managers. You want them to know who you are, what you are doing, why you are doing it (the benefits to the company), and on the authority of what senior vice president you are doing it. Then you want to make them comfortable with the idea that you will be asking mulitple series of ever more detailed questions as the project moves forward. They should feel free to delegate the responses to technically savvy subordinates, but the deal is they have to make it a priority for those subordinates to respond to you.
If that's all you have time for in your initial interview, you will have accomplished a lot. The actual technical questions can be handled by follow-up email and phone calls if necessary.
If there is additional time, you should ask these managers to sketch the architecture of the systems they are responsible for. If you give them some advance notice, some of them may prepare a document or at least some sketches. Others may just refresh their memories and then brain dump on a white board. Bring a digital camera for the white board.
What sorts of things should I include in this manual
that would be useful to the technical staff?
Things I would want to know:
1. Data flow diagrams (DFDs) show the exact names of software modules and databases and the exact names of the arguments that pass between them, as well as the direction or directions in which they pass. There are tools that make the creation and viewing of DFDs relatively straightforward.
2. Flowcharts show program logic. Again, there are useful tools. (I think Visio probably does both kinds of diagrams, but there are more sophisticated tools, too, that may already be available in your company.)
3. Source code. You should personally inspect samples of source code if developers tell you that it is already internally documented. If you can see that people have diligently followed consistent rules about documenting the software internally, then all you have to do is document how to access it in its repository. Otherwise you may need to get into it more deeply.
4. APIs. How, exactly, do the various programs communicate with each other and with the outside world.
5. Database schema. These exist; you just have to capture them.
6. What software runs on which machines, at what locations, and how often?
7. Network topology (Visio, again).
8. On the network topology, identify the specific device at each node, by brand/model/serial number if necessary.
9. Equipment list: For each device, what are the installed options, current revision level of its operating system and all installed software? Is it ghosted? If so, where is the ghosted image? What are the procedures and sequences for rebuilding the machine if necessary? (This is only important if there are particular machines with balky combinations of software on them.)
10. Is there a particular sequence in which devices and services need to be started under various conditions (power failure, cold boot, warm boot).
11. What are the security controls? What procedures need to be followed when someone is hired or fired? What is the backup routine? Where are backups stored? What is the rotation schedule for backup media?
12. Of everything listed above, which elements are subject to maintenance and and upgrade? (You need to provide a mechanism--and a set of procedures--for keeping your document up to date.)
Note that a lot of the above material is of interest to narrow audiences and should be in separate documents. And a lot of it can be included by reference to manufacturer's documentation. You don't have to _write_ all of it; you just need to understand it all at some level and be able to link to it reliably.
Since this is from scratch, what technique should I
use to estimate completion time? Does anyone have an
average number of pages per day of writing for an
operational manual? Is there a good source for such
things?
I documented a fairly complicated system (several different platforms, several different languages, massively complex network, unavailable SMEs) in about four months IIRC. YMMV.
I've done this sort of thing before, but never from
scratch and am open to suggestions.
Start with a single-sourcing mindset so that you can make operational procedures available online to the people who need them and simultaneously maintain a comprehensive printed doc as the information changes. In particular, you should build an interface to the database that allows new or updated information to be input by authorized users and then edited by the document owner (you or your successor) before it is committed to the database as a change.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L. http://www.cafepress.com/cp/store/store.aspx?storeid=techwhirl
Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save!
http://www.ehelp.com/techwr-l
---
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:
- RE: Operational Manuals - Please Help, Andrew Dugas
References:
Operational Manuals - Please Help: From: Anthony
Previous by Author:
Re: CorelDRAW /WordArt conversion
Next by Author:
Re: Operational Manuals - Please Help
Previous by Thread:
Operational Manuals - Please Help
Next by Thread:
RE: Operational Manuals - Please Help
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads