Best places to put topics when they're needed twice

Subject: Best places to put topics when they're needed twice
From: Editor in Chief <editorialstandards -at- gmail -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com >> TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sun, 3 Nov 2013 12:42:23 -0500

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


Follow-Ups:

Previous by Author: Re: Another word game - need a word sort of like "template"
Next by Author: Re: Best places to put topics when they're needed twice
Previous by Thread: re: Question about Google Plus vanity URL
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