RE: Creating a Documentation Kit

Subject: RE: Creating a Documentation Kit
From: "Steve Hudson" <steve -at- wright -dot- com -dot- au>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 19 Oct 2001 10:04:49 +1000

Some thoughts on the subject from one who has done this before and is doing
so again as we speak lol :-) Zip it all this stuff up in its own dir, email
it out.

#1: Provide these materials

* Template Install instructions. Include an instruction to append their std
word shortcut with "/tZ:\Path\Templates\TheOne.dot"

* Template Users' Guide

* Style Guide, Designs Register & Documentation Procedures Manual, or links
to production copies of these.

* A quick reference sheet with any custom key-shortcuts, and useful word
ones.

#2: Provide these functions (I have pre-done macro code for a lot of this
stuff if required):

* Template manual-install menu entry (I use a ! menu - it also includes
stuff like SetMyOptions and FixMyToolbars)

* My automagic (based on std ms code) AutoCorrect Updates document packed
full of your style guide's enforcements.

* Custom Dictionaries. Arrange for regular collection and dissemination of
these. I am in the process of completing this rollout via a document similar
to autocorrect.

* A macro to hard set local numbering options and styles.

* "Help > Feedback" button to send you an email

* "Help > About this template" describing the user guide and providing the
template release.version.build number.


#3: Std boilerplate texts. Differentiate between boilerplates (BP) and
skeletons. BP is predone chunks. Empty pre-formatted tables, copyright
notices, address blocks blah blah. Skeletons can be pre-done heading
structures to full independent document designs.

I haven't fully completed it yet, but I am hoping to build a BP menu
directly from a path. At the moment the menu option triggers a macro that
reads the locale and gets the correct server path before following that addy
as a hyperlink. Too simple. That way each geographic location tells me their
server root for where the designs will sit (I split them merely into Designs
and Forms at this point) and I whack that info into my localiser macro.


Most of my stuff can be found on the HATT site. Hopefully it will also be
available here (Tech-Whirly birds) short-a-lye. Note that the plan outlined
above gives you control over their template, invocation of word,
dictionaries, autocorrect entries, toolbar placements, styles AND numbering.
Whew. I do believe that's all. The rest is fancy trimmings :-)

Steve Hudson
Principal Technical Writer
Wright Technologies (Aus)
steve -at- wright -dot- com -dot- au
(612) 9518-1822
The best way to predict the future... is to create it!



-----Original Message-----
From: Cara O Sullivan


To meet the need, I've proposed the idea of a documentation kit that
contains a MS Word template (this is an internal standards); a how-to guide;
and a pre-formatted Excel project spreadsheet that will help team leads
plan and track the progress of their documentation. I'll be available to
help plan the projects, review drafts and provide editing support.

Has anyone on this list ever done anything similar to this? If so, what
pitfalls should I avoid? And is there anything else I could include in the
kit to make it more effective? This kit will be used by people who know lots
about their jobs--some will be good writers and most probably won't be. They
will also be people who don't want to be writing. I've tried to design this
kit with that in mind. This kit really takes the place of a global team of
writers, which is what we should have but simply can't afford in the current
economic environment.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit http://ieeepcs.org/2001

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

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


References:
Creating a Documentation Kit: From: Cara O Sullivan

Previous by Author: RE: prototype for doc repository
Next by Author: RE: Creating a Documentation Kit (Long Response)
Previous by Thread: Re: Creating a Documentation Kit
Next by Thread: RE: Creating a Documentation Kit


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

Sponsored Ads


Sponsored Ads