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