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.

http://webhelp.madcapsoftware.com/flare10/Default.htm

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.

http://www-01.ibm.com/support/knowledgecenter/SSLKT6/sslkt6_welcome.html


On Tue, Mar 10, 2015 at 4:28 PM, Nina Rogers <janina -dot- rogers -at- gmail -dot- com>
wrote:

> 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
> title:
>
> 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
> product."
>
> 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!
>
> Best,
> 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
> info.
>
> 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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -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 info.

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


References:
Differentiating between software versions in help articles: From: Nina Rogers

Previous by Author: Re: "Technical Writing: How to Break Into this Lucrative World"
Next by Author: Re: Thanks! (was Re: Possessive form of name ending with apostrophe?)
Previous by Thread: Re: Differentiating between software versions in help articles
Next by Thread: RE: Differentiating between software versions in help articles


What this post helpful? Share it with friends and colleagues:


Sponsored Ads