Style Guide Question - documenting paragraph tags?

Subject: Style Guide Question - documenting paragraph tags?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 01 Nov 2005 14:37:01 -0500


Julia Cemer wondered: <<I am in the process of updating our style guide. As I was researching, I read somewhere that you should document your paragraph and character tags (we use Frame). Currently, our style guide lists all the paragraph and character tags and their appropriate use (Use only after Numbered1 style, etc.). However, what I read seemed to indicate you should break down exactly what makes up the style (font size, word spacing, weight, etc).>>

It's a good idea to list the specifics of how the tags should be used, but probably overkill to include all the style information. The main reason for doing this in the past was as an emergency measure, in case you had some major network crash and lost your template; documenting all these details would let you manually recreate the template from the description in the style guide. But if you maintain good backups of your documents, there's little need for this: the information can be retrieved quickly simply by opening the template.

That being said, there's little harm in completely documenting your styles if you have time. It's probably more convenient to have this kind of information available "at a glance" than to have to open each style in the template to review its parameters. That being said:

<<Does any one have suggestions on the best way to do this?>>

The "best" way always depends on the problem you're trying to solve. But here's one effective way: present the information in a nicely formatted table, with one column per parameter (e.g., font = Times New Roman 12), and the styles nested under headings that help readers locate the appropriate style (e.g., gather all the headings together, all the body text styles together, etc.).

Another trick I've done with considerable success in the past is to present a thumbnail (ca. 1/3 the size of a real page) of a typical page that contains all the main styles, then use callout arrows to point at each element of the page, name the style, and summarize its key attributes. You can simplify the presentation quite a bit if you define the parent styles (the ones on which others are based) in some detail, then for all child styles (the ones based on those parents), say "based on [parent name]", and present only the parameters that change.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Try WebWorks ePublisher Pro for Word today! Smooth migration of legacy
RoboHelp content into your new Help systems. EContent Magazine Decision-
maker review (October 2005) is here: http://www.webworks.com/techwr-l

Doc-To-Help 2005 converts RoboHelp files with one click. Author with Word or any HTML editor. Visit our site to see a conversion demo movie and learn more. http://www.componentone.com/TECHWRL/DocToHelp2005

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



References:
Style Guide Question - documenting paragraph tags: From: Julia Cemer

Previous by Author: Capitalize generic "Logic Engine"?
Next by Author: Capitalize generic "Logic Engine"? (take II)
Previous by Thread: Style Guide Question - documenting paragraph tags
Next by Thread: Re: Style Guide Question - documenting paragraph tags


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


Sponsored Ads