Re: Need examples of system documentation

[Peter Neilson <neilson -at- windstream -dot- net>]

Daniel's suggestion is the best one. The correct approach is most likely 
to start with a documentation plan that spells out--in some degree of 
detail--the (several) needed documents and suggests the order of their 
creation. The ones Daniel mentioned are probably of the highest 
priority. If they do not exist, they really should be written, and 
quickly, then revised fairly soon afterwards.

A full plan will also cover the "concept" docs. Make the plan very 
public, and allow meetings at which it can be revised, but don't let the 
docplan become a god or even your own highest priority. It's only a tool 
to keep you and the rest of your team on target.

In general, the projects where I've used docplans have worked out well, 
and the ones where I let the plan get pushed aside are the ones that failed.

Daniel Ng wrote:
> *This message was transferred with a trial version of CommuniGate(r) Pro*
> Hi Deltaskye
> This looks like something quite practical within IT administration
> documentation instead of something for analysis and design.
> 
> - how to backup and restore (the roles responsibilities), the current
> schedule, and the type of backup being done.
> - how to configure BEA, the config files, the key values, what to leave at
> default, what should happen, enabling logging, disabling logging. The most
> important configurations for troubleshooting modes, for performance/daily
> operations
> - External data interface- if you have a DBMS like SQL Server, it
> automatically generates a relationship diagram (ERD) of tables, keys, etc.
> Visio might be able to do it too with some work.  
> 
> The number of tiers, Application Tier, Data Tier, Client Tier, list of
> workstations?
> Server computer/IP add
> Data Tier/IP add
> 
> Something additional
> - Common errors and solutions
> 
> Administrators Guide
> Technical Maintenance Handbook
> Database Maintenace Handbook
> Disaster Recovery Guide
> 
> -----Original Message-----
> From: deltaskye [mailto:deltaskye -at- yahoo -dot- com] 
> Sent: Saturday, September 27, 2008 11:19 PM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Need examples of system documentation
> 
> I am returning to IT system tech writing after an absence of four years. My
> client wants me to document a system that is already in place; the engineer
> who designed it did not write anything down! 
> 
> I will be working with a new engineer to try to document the system (not for
> end-users, for the company's internal/engineering use). The engineer will be
> the technical SME and I will be the scribe and desktop publisher. The system
> is used by staff to register new customers for a service, document customer
> service calls, and transmit each day's activities to another system.
> 
> The engineer has asked me to provide him some examples of what the
> documentation might look like. I have all kinds of stuff generated when
> other customers followed an organized SDLC as they were designing a system.
> I'm looking for ideas on how to frame the documentation as the engineer and
> I try to document a system that someone else designed (and who is no longer
> available).
> 
> I don't know if the following is helpful, but here are some of the topics
> the engineer has suggested:
> 
> External data interfaces
> Oracle database management system
> BEA configuration
> System backup/restore
> 
> Thanks!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ComponentOne Doc-To-Help gives you everything you need to author and 
publish quality Help, Web, and print content. Perfect for technical 
authors, developers, and policy writers. Download a FREE trial.
http://www.componentone.com/DocToHelp/

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.