Re: Repeating blocks of text: How (or if?) in unstructured FM
I have several similar procedures for creating a new software
application in the IDE. The user chooses a procedure based on the
template he or she is using as a start. In each procedure, the user
follows a path based on what results he or she wants.
The procedures share a lot of steps, but some are different. For
example, if I have three procedures, they have the following pattern.
Notice that some steps are common to all three procedures, but I write
them out three times:
[SNIP]
I write out all three procedures in their entirety, because as much as
possible I want the user to see all the steps in one place, without
jumps around the documents.
Does this make sense? Would it be somehow better to craft one procedure
with various options? Three procedures that "thread" through the steps,
so that I write each step only once?
If I put a common step (for example Step B) three times, what's the best
way to do it in FM? Should I use text insets?
Hi, Joe:
You're verging into content management and reusability. As an end-user, I'd agree that each instance of a procedure should be presented in its complete form, and that each identical step should be written identically.
One problem here involves knowing the learning styles of the individuals who make up your audience. Some may have the learning habit of skimming the material and assume that procedures that begin similarly and seem to be mostly similar, are likely to be identical throughout. If this could lead to erroneous operation, even though it's the reader's habit, it's a good idea not to write in a way that reinforces it.
Reusing complete procedures, such as setup, safety steps and precautions, and shutdown operations, can help users build complete habits.
Depending on the length of the material, a cross-reference could suffice for reusing a paragraph, a text inset (ranging from several paragraphs to multiple pages) could suffice for medium amounts of material, and a complete file brought into a book could suffice for large amounts of repeated material.
No matter which approach you take - whether you use only one, or a combination of them - document it in within the files, for future maintainers. Content that's in a flow-tagged text frame on a master page does not appear on body pages, which makes these frames one good place to store documentation that travels with the file and all its copies. Text frames on reference pages are another.
HTH
Peter Gold
KnowHow ProServices
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WebWorks ePublisher Pro for Word features support for every major Help format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -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%40infoinfocus.com
To subscribe, send a blank email to techwr-l-join -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.
Previous by Author:
Re: Project management resources
Next by Author:
Re: MS Word readability index
Previous by Thread:
Repeating blocks of text: How (or if?) in unstructured FM
Next by Thread:
No good deed (was My doc was too good)
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads