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: Differentiating between software versions in help articles
Subject:RE: Differentiating between software versions in help articles From:"David Artman" <david -at- davidartman -dot- com> To:"Nina Rogers" <janina -dot- rogers -at- gmail -dot- com>, techwr-l -at- lists -dot- techwr-l -dot- com Date:Fri, 13 Mar 2015 06:26:40 -0700
I concur with Gene and Julie--each version of the software should point
to its own, unique helpset. If those sets should happen to have
identical articles, oh well: storage is cheap and single-sourcing is A
As far as validating/indicating which version of help the user is
viewing, that would be a trivial thing to show in the header (along
with modified date in footer, perhaps). In essence, that would be the
helpset's 'site title'; and each article would be the H1 of the topic
(at highest level):
Software 2.0 Help - Fooing the bar
Software 2.0 Help
=Fooing the bar=
I think that trying to indicate applicable version in the title will
become a nightmare. What happens once you're at v4.5--you going to have
article titles that read "Fooing the bar (1.0, 2.0, 2.2, 2.5, 3.0, 3.5,
4.0, 4.5)"? What happens when v3.5's "Foo" function is slightly
different from v3.0? And more importantly: *Who cares* what versions a
given article applies to, if users tend to only have one version
installed and that version consistently points to its correct topics?
Your manager's instinct to show all versions might be a case of one's
knowing how the sausage is made leading one to think sausage eaters
want to know (they really, really don't!).
Adobe TCS 5: Get the Best of both worlds: modern publishing and best in class XML \ DITA authoring | http://adobe.ly/scpwfT