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.
How to manage projects for multiple software versions?
-
- Senior Propellus Maximus
- Posts: 2089
- 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?
Welcome to the forums!
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.
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.
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
Re: How to manage projects for multiple software versions?
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.
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.
-
- Propeller Head
- Posts: 88
- Joined: Wed May 25, 2016 3:35 pm
Re: How to manage projects for multiple software versions?
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.pjtwriter wrote:I may use the Export Project feature to create a backup before I do anything too drastic.
Technical Writer using and experimenting with Flare version 12.0.5991.
-
- Senior Propellus Maximus
- Posts: 2089
- 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?
The joys of being on the other side of the worldpjtwriter wrote:Thanks for the speedy response...
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
Re: How to manage projects for multiple software versions?
Hi Steve,SteveS wrote:you might need to create 2 conditions for each version, one for include, one for exclude,
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.
Re: How to manage projects for multiple software versions?
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.)
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."
Re: How to manage projects for multiple software versions?
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.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.)
P.
Re: How to manage projects for multiple software versions?
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.
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."