RE: Best places to put topics when they're needed twice

Subject: RE: Best places to put topics when they're needed twice
From: "Sharon Burton" <sharon -at- anthrobytes -dot- com>
To: "'Editor in Chief'" <editorialstandards -at- gmail -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sun, 3 Nov 2013 10:09:51 -0800

Snippets.

For example, in the Config guide, you have a "container doc" that includes
all the simple info as snippets.

Admin guide? Another "container doc". Same snippets and then the other info
as snippets as well.
Doesn't break your breadcrumbs and still lets you do reuse.


sharon

Sharon Burton
951-369-8590
www.sharonburton.com
Twitter: sharonburton
Author of 8 Steps to Amazing Webinars,
available on Amazon and bn.com

-----Original Message-----
From: techwr-l-bounces+sharon=anthrobytes -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+sharon=anthrobytes -dot- com -at- lists -dot- techwr-l -dot- com] On
Behalf Of Editor in Chief
Sent: Sunday, November 03, 2013 9:42 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com >> TECHWR-L
Subject: Best places to put topics when they're needed twice

All,

We use MadCap Flare 9.x
Our template is organized to output both a single hefty Webhelp and a set of
PDFs with the same content. The ToC for the WebHelp looks a lot like the set
of ToCs for the PDF outputs.

I think the Admin Guide (a "stand-alone" PDF in the PDF doc set, but a mere
section of the overall ToC in the WebHelp version of the docs) should
include the how-to for everything, including all two, three, or four
versions of how to configure and use any given feature. The Configuration
Guide, on the other hand, is meant to show just the "most likely" path to
getting the system up and running as (we believe) more than half our
customers would need it.

The problem is duplication.

If we have all three ways to implement Feature D in the Admin Guide, we have
to repeat the most common implementation instruction for Feature D in the
Config Guide.

It's just links in a ToC, you say, so just make two links to that
most-popular Feature D instruction topic, one link in the Config Guide, and
one link (along with the other two, less-used methods) in the Admin Guide.
And it doesn't matter where the actual topic file lives, and there's only
the one version of it to maintain..... easy-peasy, right?

Not so fast. We feature Breadcrumbs navigation aid prominently at the top
of every Webhelp topic. If a single topic has more than one link in the ToC,
it breaks Breadcrumbs (at least, as they are implemented in WebHelp, by
Flare.

What do other people normally do?

In case the above was obscure, here's an example:

Every computer clock drifts. Many applications need reliable time, both
within and among connecting systems. We provide three options to achieve
that:

a) use simple Network Time Protocol (NTP) to receive a signal from a
standard internet time source, and keep your system's clock adjusted that
way.

b) do the same as "a)", but with secure NTP, which uses certificate-based
authentication to ensure no nefarious substitutions of time-correcting
signals

c) if you aren't allowed to use NTP, then correct your own time with
built-in drift-correction tools - it works, but is a bit more hands-on.

We estimate that most customers would (or should) use method "b)", so that's
the one that appears in the Config Guide. But, for completeness, that
method should appear in the Admin Guide, alongside the other two methods. .
. especially when a customer might keep only the Admin Guide (PDF or
printout) handy.

So, duplicate the topic, and risk the copies getting out of sync?
Or use just one topic for a description/instruction, point to it from two or
more places, and live with the fact that it breaks the Breadcrumbs feature?
OR.... some third way.

--
__o
_`\<,_
(*)/ (*)
Don't go away. We'll be right back.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for
authoring.

Learn more: http://bit.ly/ZeOZeQ

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

You are currently subscribed to TECHWR-L as sharon -at- anthrobytes -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


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

Looking for articles on Technical Communications? Head over to our online
magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public
email archives @ http://techwr-l.com/archives




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

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

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-leave -at- lists -dot- techwr-l -dot- com


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

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
Best places to put topics when they're needed twice: From: Editor in Chief

Previous by Author: Re: Footnotes - acceptable in technical documentation?
Next by Author: Re: So now we are content engineers?
Previous by Thread: Re: Best places to put topics when they're needed twice
Next by Thread: Re: Best places to put topics when they're needed twice


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

Sponsored Ads


Sponsored Ads