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:Julie Stickler <jstickler -at- gmail -dot- com> To:Technical Writing <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Wed, 11 Mar 2015 11:05:24 -0400
In order to know how to answer your question, we really need to know how
you are delivering your Help.
- Is it delivered with the software (embedded)?
- Is it hosted on a Help server?
- Is it hosted on a Wiki?
It sounds like you're hosting it in some way. Is there any reason why you
can't have separate systems for each version, and have the software link to
the appropriate version?
MadCap software posts each version of their Help online, and each version
is posted separately. You can see the version number in the URL below.
The company I used to work for about a decade ago was bought by IBM, who
posts links to previous versions of the documentation on their site. The
link below lets you access help for versions 7.1 through 7.6.
On Tue, Mar 10, 2015 at 4:28 PM, Nina Rogers <janina -dot- rogers -at- gmail -dot- com>
> Greetings, all!
> My company recently released a "2.0" version of its software. Many of our
> users are still using 1.0 and will continue to do so through 2016. While
> some of the functionality between the two versions is similar (i.e., a
> single help article for both will do), there are a lot of changes. So,
> while maintaining the help articles for 1.0, I've been writing many new
> articles for 2.0 only.
> Here's the challenge: What's the most graceful way to indicate which
> version(s) of the software a help article applies to, particularly when it
> applies for both versions? Originally, I was designating versions in the
> Managing User Accounts (1.0)
> Managing User Accounts (2.0)
> For those articles that applied to both versions, I wasn't putting a
> designation in the title, though I was preceding each article with a note
> along the lines of, "This information applies to both versions of our
> My manager would like to make it clear in the title when the article
> applies to both versions. He suggests something like this:
> Managing User Accounts (1.0, 2.0)
> That doesn't look so bad, but when the title is a few words longer, it
> starts to look kind of messy. I personally don't like the idea of
> indicating both versions in the title; it seems like that should be
> understood, and if it's not, then there's the note at the beginning of the
> article. But my manager isn't convinced.
> Just wondering how some of you have handled similar challenges, where you
> have a support site with lots of articles--some pertaining to one version
> of the software, some pertaining to another, and many pertaining to both.
> Thanks in advance!
> Nina Rogers
> Adobe TCS 5: Get the Best of both worlds: modern publishing and best in
> class XML \ DITA authoring | http://adobe.ly/scpwfT
> You are currently subscribed to TECHWR-L as jstickler -at- gmail -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
> 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
Julie Stickler http://heratech.wordpress.com/
Blogging about Agile and technical writing
Adobe TCS 5: Get the Best of both worlds: modern publishing and best in class XML \ DITA authoring | http://adobe.ly/scpwfT