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.
Differentiating between software versions in help articles
Subject:Differentiating between software versions in help articles From:Nina Rogers <janina -dot- rogers -at- gmail -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Tue, 10 Mar 2015 16:28:09 -0400
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!
Adobe TCS 5: Get the Best of both worlds: modern publishing and best in class XML \ DITA authoring | http://adobe.ly/scpwfT