TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
