How to manage projects for multiple software versions?

This forum is for all Flare issues related to getting started and installing the application.
Post Reply
pjtwriter
Jr. Propeller Head
Posts: 2
Joined: Tue Oct 10, 2017 8:12 am

How to manage projects for multiple software versions?

Post by pjtwriter »

I'm new to MadCap Flare and have inherited a well-organized project. I write User Guides for a software product. I'm wondering how to handle versioning, as our product development cycle has two major software releases per year. I've seen some comments about parent-child projects, although I have to do some more reading on this to see what that type of organization means.
Specifically, I have the following basic questions:
1) Is there a way to clone a project for our next product release?
2) Does it make sense to clone a project or is there a better way to maintain two or more versions of our product documentation?

Thanks for tolerating my basic questions. I've been reading the manuals, watching videos, and searching the message boards, but haven't found anything that quite matches my needs.
SteveS
Senior Propellus Maximus
Posts: 2087
Joined: Tue Mar 07, 2006 5:06 pm
Location: Adelaide, far side of the world ( 34°56'0.78\"S 138°46'44.28\"E).
Contact:

Re: How to manage projects for multiple software versions?

Post by SteveS »

Welcome to the forums! :D

How much content gets changed with each release? Is it complete topics, or just blocks of text? Are images changed? You say the content has been well maintained, how were updates treated in the past?

Not knowing these things it's hard to come up with an ideal approach.

I would lean towards keeping versioning within the same project, so when you access the project you have a history of previous releases. You can use conditioning to show or hide content based on a version (you might need to create 2 conditions for each version, one for include, one for exclude, or you can just create an include and exclude for the current version). If you create a new topic for your versioning I'd be more inclined to go down the path of a new MasterTOC for each version.

One method of cloning a project is to use the Export Project Wizard, on the Project tab (click export project to start the wizard). If you wish to use a new project you can also use an existing project as a start point in the start new project wizard.

If you use source control you can just update each topic with new content and use source control for handling the versioning.

Hope this gives you food fo thought.
Image
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
pjtwriter
Jr. Propeller Head
Posts: 2
Joined: Tue Oct 10, 2017 8:12 am

Re: How to manage projects for multiple software versions?

Post by pjtwriter »

Thanks for the speedy response. This is excellent food for thought and I'm going to look further into conditions. Since I'm new to the company, I'm not certain how much content will require updates, although I know that the UI is getting a face lift, so all the screen shots (and there are many) will need to be replaced. Unfortunately, we don't use source control for documentation, although it's on my list of proposed projects.
This is the first time that I (the sole writer) have to consider maintaining multiple versions because Flare was only introduced for the previous product release. Prior to that, everything was done in Word (yikes!). I'm glad I joined the company after the transition to Flare. I came from a FrameMaker shop and I'm finding Flare to be a joy.
I may use the Export Project feature to create a backup before I do anything too drastic.
paintedturtle
Propeller Head
Posts: 88
Joined: Wed May 25, 2016 3:35 pm

Re: How to manage projects for multiple software versions?

Post by paintedturtle »

pjtwriter wrote:I may use the Export Project feature to create a backup before I do anything too drastic.
You can zip the entire project in a few clicks on the Flare UI: Project > Zip Project > Zip Project. It saves it in a PDF in about 5 minutes. I do this daily as a backup because I'm paranoid. :D
Technical Writer using and experimenting with Flare version 12.0.5991.
SteveS
Senior Propellus Maximus
Posts: 2087
Joined: Tue Mar 07, 2006 5:06 pm
Location: Adelaide, far side of the world ( 34°56'0.78\"S 138°46'44.28\"E).
Contact:

Re: How to manage projects for multiple software versions?

Post by SteveS »

pjtwriter wrote:Thanks for the speedy response...
The joys of being on the other side of the world :shock:
Image
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
oceanclub
Sr. Propeller Head
Posts: 277
Joined: Thu Oct 10, 2013 4:45 am
Location: Dublin

Re: How to manage projects for multiple software versions?

Post by oceanclub »

SteveS wrote:you might need to create 2 conditions for each version, one for include, one for exclude,
Hi Steve,

This sounds interesting, can you give an example of how it is used? I'm still not sure of the optimal way of using condition tags for versioning in Flare.

In my last company, we set up condition tags for "<version>_only" and "<version>_onwards". For example:

1.0_only
1.0_onwards
2.0_only
2.0_onwards
...
4.0_only
4.0_onwards
etc

This worked fine for material only a particular version or material that was introduced in a version and stayed in the product. But it complicated issues where, say, a product was introduced in 2.0 and removed in 4.0. There we either had to (a) multiply the text three times and have each wrapped by a 2.0_only, 3.0_only and 4.0_only tag OR split up the topic and then have that particular text in a standalone topic, which was only in the 2.0, 3.0 and 4.0 TOCs. This was a lot of fussing around.

(We also used condition tags for clients, so condition tags were ANDed not ORed. Which meant we couldn't apply multiple version tags to the same material as that condition would never satisfy.

So if anyone has the optimum way of doing it I would love to know.

P.
Paulie
Sr. Propeller Head
Posts: 140
Joined: Sun Mar 01, 2015 3:01 pm

Re: How to manage projects for multiple software versions?

Post by Paulie »

What versioning system do the developers use to version their code? I'd be surprised if they don't already have a system in place that you can leverage off.

If I was in your position, and there was no development versioning system to fall back on, I'd probably set up an SVN repository for the Flare content. In the long run, it would be much less problematic than trying to maintain versions via conditions, (imagine all the conditions when you get to v10, or if the company goes agile and starts having a release every few weeks.)
"In an ideal world, software should be simple, well designed, and completely intuitive to end users. In the real world, good documentation is king."
oceanclub
Sr. Propeller Head
Posts: 277
Joined: Thu Oct 10, 2013 4:45 am
Location: Dublin

Re: How to manage projects for multiple software versions?

Post by oceanclub »

Paulie wrote:What versioning system do the developers use to version their code? I'd be surprised if they don't already have a system in place that you can leverage off.

If I was in your position, and there was no development versioning system to fall back on, I'd probably set up an SVN repository for the Flare content. In the long run, it would be much less problematic than trying to maintain versions via conditions, (imagine all the conditions when you get to v10, or if the company goes agile and starts having a release every few weeks.)
Yes but then we'd have multiple copies of all topics to maintain which surely beats the point of having single-sourcing in the first place? :) I think the above would only work for companies where you can release a version of the documentation and never ever have to update it again.

P.
Paulie
Sr. Propeller Head
Posts: 140
Joined: Sun Mar 01, 2015 3:01 pm

Re: How to manage projects for multiple software versions?

Post by Paulie »

It's the approach that we currently use, and I find that it works well for my company. We currently have 8 branches (versions) that are actively being maintained, so it does support that workflow. (Because most things in Flare are XML-based, it isn't that difficult to backport changes to other revisions.) I personally find multiple branches in SVN far easier to manage than multiple 'version' conditions. As mentioned in an earlier post, conditions can soon get messy if content is in some combination of revisions and not in others.

At the end of the day, every company, and every use case is different. If you find that working with conditions for everything is easier for you, then by all means go for it. The best approach for will will ultimately come down to the intricacies of your company, and how many changes there are likely to be between revisions. I just wanted to make sure you are aware of another potential approach, so that you are aware of all of the options and make the best decision for your unique set of circumstances.

Edit: I should also be clear, that I don't use Flare SVN integration, I instead use the tools that come with Tortoise SVN to manage my revisions.
"In an ideal world, software should be simple, well designed, and completely intuitive to end users. In the real world, good documentation is king."
Post Reply