atw: Re: Duplicating material in procedures [SEC=UNCLASSIFIED]

On 15/12/05, Silcock, Howard DR <Howard.Silcock@xxxxxxxxxxxxxx> wrote:
>
> the developers may be working on the document again...


Ahhh, I see your problem now. Solution - give up :) Or shoot the developers.
Or shoot yourself.

Seriously though, there's no foolproof (or developer proof) method.

In Word I tend to keep my common text in a separate document (still with
bookmarks) and use includetext fields, that way you could give the
developers only the document with the common source to update - but it
depends on your ratio of common text to standard text and what the
developers need to touch. And they can still muck things up but probably not
as badly.

In an XML document I guess it might be different, as the document structure
> would probably be more apparent to anyone working on it and you wouldn't be
> using XML if you didn't have these kinds of tricks in mind.
>

Developers seem to get their heads back together once they can use vi or
some other text editor (which, of course, you can do with XML). They just
can't seem to apply themselves to learn even rudimentary skills with Word
(and I don't entirely blame them - but then if they won't, they shouldn't
touch documents).

(Yes, I know anyone can easily inspect the fields in a Word document too,
> but it seems people just don't expect them to be present or used that way or
> understand why they're there.)
>

One thing you could do is make sure anyone who works on your documents has
field shading always on.

So for me the option of the more intelligent solution you're suggesting just
> wasn't viable!
>
> Howard
>
>  -----Original Message-----
> *From:* austechwriter-bounce@xxxxxxxxxxxxx [mailto:
> austechwriter-bounce@xxxxxxxxxxxxx] *On Behalf Of *Melanie Kendell
> *Sent:* Thursday, 15 December 2005 12:13
> *To:* austechwriter@xxxxxxxxxxxxx
> *Subject:* atw: Re: Duplicating material in procedures [SEC=UNCLASSIFIED]
>
> Hi Howard
>
> From the writer's perspective duplication is bad - more work, more chance
> of error, divergence, etc.
>
> From the reader's perspective you are right, they only want to see stuff
> that works for them and not to have to go from pillar to post to get to it.
>
> So, what you do is single source the common material but output the two
> versions in the publication - what editor are you using? You can do this
> with includetext fields in Word or text inserts in FrameMaker. Or, if you
> were using XML... :)
>
> -Melanie
>
>
> On 15/12/05, Silcock, Howard DR <Howard.Silcock@xxxxxxxxxxxxxx> wrote:
> >
> > I'm currently editing some procedures that have a large amount of common
> > material. The two procedures are designed to produce the same outcome
> > but are used in different circumstances. (You follow one for making an
> > update from a CD/DVD and the other for doing it over the network.)
> >
> > My first thought, when I realised that there were so many completely
> > identical steps in these procedures, was to strip out all the common
> > steps and put them in one place, then direct the reader there when he or
> >
> > she reaches the appropriate point in either procedure.
> >
> > This has obvious advantages from the writer's perspective. It makes it
> > much easier to maintain and keeps down the overall length of the
> > document. Also, in this case at least, it avoids repeating the same
> > screenshots twice each in the document - and hence having a list of
> > figures that contains quite a few duplicate captions.
> >
> > Yet as soon as I thought about it from the reader's perspective I
> > realised that there were advantages in keeping it as it is, with all the
> >
> > duplicated text and figures. The reader will probably only need to look
> > at one of the procedures - why should she or he care what's in the
> > other? And who wants to jump around in a document to find out what to
> > do? The bulk of the document could be a disadvantage in some cases, but
> > in this case the document is actually only fairly short anyway. The
> > important thing is to make it easy for the reader to find what he or she
> > wants, then be able to follow it through without too much unnecessary
> > page-flipping.
> >
> > I believe strongly that our job as writers or editors is to make life
> > easy for the reader, even at the cost of extra work for ourselves. But,
> > on the other hand, I also recognise that extra work for us can make more
> > room for mistakes, which could make the reader's life even harder in the
> > end.
> >
> > Has anyone else grappled with this issue?
> >
> > Howard
> >
> >
> > ==================================
> >        Howard L. Silcock
> >         Technical Writer
> >     Common Services SOE Program
> > Network Infrastructure Development
> >        Department of Defence
> >          (02) 626 58395
> > ==================================
> >
> > **************************************************
> > To post a message to austechwriter, send the message to 
> > austechwriter@xxxxxxxxxxxxx
> > .
> >
> > To subscribe to austechwriter, send a message to
> > austechwriter-request@xxxxxxxxxxxxx with "subscribe" in the Subject
> > field.
> >
> > To unsubscribe, send a message to austechwriter-request@xxxxxxxxxxxxxxxxx 
> > "unsubscribe" in the Subject field.
> >
> > To search the austechwriter archives, go to
> > www.freelists.org/archives/austechwriter
> >
> > To contact the list administrator, send a message to
> > austechwriter-admins@xxxxxxxxxxxxx
> > **************************************************
> >
>
>

Other related posts: