MadCap Software Forums

Hi,

I currently have a bit of a dilemma with versioning my user guides within Flare.

The dilemma is that I have different TOCs for different versions of the user guides we write. When I'm working on the newer version of the user guide TOC (and it's not ready for release) I need to maintain the older TOC version as well because we may need to re-release the old version while we're still working on the next one.
How do you go about single-sourcing this though?

I end up needing two different TOCs (which is essentially fine because there are generally new topics added). The problem comes with the fact that I have a versioning page and a cover page for each user guide (not each version of each user guide). I want it this way because the cover page should remain consistent across each user guide version and also because all approval should be updated on the one document. However, I can't do an 'automatic build' because the cover page will only contain the last version that I put in the cover page, not the version for the appropriate TOC. The easiest workaround is to use multiple topics for the cover page; one cover page per TOC. But then it isn't single-sourced. The other options is to condition the contents of the cover page so that I can select which version of the user guide I'm after -- but there are many different versions (each change gets either an alphabetical increase or a numerical increase -- e.g., V01a, V01b, V01c) and the conditions list would be gigantic. (Also, the versioning system cannot be changed as it's organisation-wide)

The other approach I'm aware of is to use target-specific variables whereby you can change the variable for the target. The problem there is that then I need to have a different target for each TOC which defeats the purpose of the target being used for the specific user guide; it becomes specific for each version.

I don't know whether anyone else has had this dilemma, but any advice would be great. I currently have a different cover page per user guide so that I could do a build and have the contents page consistent. The versioning page is a little more tricky though because I only want one version page stating the version changes between released versions. Perhaps I should store that somewhere else? Make release notes in our wiki or something? (Just thinking outloud)

Also, we don't currently have source control -- it's up to me to do backups and version control manually (which I do). I'm a little stumped how to optimise this in Flare though.

Thanks for your help and knowledge Hope the ramble made sense..

Oooooh, you should seriously consider source/version control. (I only know Subversion, so that's what I'll talk about.) You could accomplish what you're after by putting your Flare project into Subversion, and then (using TortoiseSVN, another Subversion client) create different Subversion branches for your different product release versions. You'd end up having a different copy of the Flare project on your computer, one for each product branch. If you make a critical change in one branch project that needs to be propagated to one or more of the other branch projects, you could do what's called a merge.

I'm certain that you could accomplish the same with other source control platforms, but others will have to pipe up about them.

I know I'm just tossing this out without a lot of detail, but I think the scheme you're using now is not scalable or sustainable. Too much manual fussing to make it all work, and as you point out, you can't easily do automatic builds. Source control can get you exactly what you're after, or at least close to what you're after.

All this said, in my opinion, making the move to source control takes understanding and planning. I suggest that you talk to your developers to see how they're doing version control of their code.

I so second Nita's reply.

I'm assuming you are documenting a product that has a software element If so, I can assure you that without source control, your developers would have exactly the same problem as you are having, but magnified. I would sit down with a friendly developer, and find out what they use and how they manage the versioning process for their software, then ask them to hook up a docs area within the same branching/versioning system as they use. Then working on the previous version of your documents would simply be a case of working in the appropriate branch, or stream or whatever your particular source control system calls the separate version "threads".

If for any reason, this is completely impossible (I can imagine a few reasons this could be the case, but they are all political, not practical, but hey, we do get embroiled in company politics sometimes) then I'd set up my own versioned structure in your manually backed-up docs area. Each time a version ships (that is, each time you start thinking about preserving one version and also being able to start making changes that apply to the next version), I'd take a complete copy of your whole document area and call it "version xxx". Include everything, whether you think it's relevant or not, just in case. Then you will effectively be managing your own release versioning too as well as your own back-ups etc. You will be using the method we used to manage our software releases when I was a software developer in the early 1980's, when version control systems were expensive and not commonplace. if your management forces you to do this, you could suggest that their developers go back to using the computers and development tools that were available in the early 1980's to develop software that is relevant and competitive in today's market.

It sounds like the source control system might be the way to go for you, but for what its worth I do something (without a source control system) which has similarities to your set up. My caveat would be - it only works because of the way our software elements grow.

In my world I have some software to document called VOS. I have to produce a manual for VOS. But VOS keeps changing...
So I actually produce a manual for VOS_vaa.bb.01, later one for VOS_vaa_bb_02 then one for VOS_Vaa_cc_01 ... I maintain these as separate targets and I use a variable called SoftwareFrom. So my target VOS_Vaa_cc_01 is just a clone of VOS_vaa_bb_02 with updated header and SoftwareFrom variables...

(This system means I can generate VOS_vaa.bb.01 v1.0 and later VOS_vaa.bb.01 v1.1 etc.. when there are errors of mine to update, rather than changes to the software I'm documenting)


I use a couple of conditional tags I call FromVersion and DroppedInVersion which I attach to text as I insert it in my topics to reflect paragraphs added at a particular version or deleted.

So I work mostly from just one TOC for half a dozen releases of software. (My cover page uses 3 target defined variables to describe itself Manual_Title valid for SoftwareFrom PublishedMonth)

Then there may come a step change where someone has reorganized lots of menus and forces a new version of the TOC, which I call, say, TOC_Vaa_cc_01_on. This one is then my master TOC in the targets from that version onwards.

It works OK so far, but I am on the cusp of going over to source control.

We don't use a version control system - though I agree with the principle that it is a good idea. Our shop has TFS used by developers, but our initial testing showed that it was WAY too slow. Most likely a network issue, but unworkable.

We keep backups on a shared network drive, and copy to local drives to work. When a new release is due, we make a copy of the whole project and store it in a sub-folder with the software version number. Further updates are all done on the latest version. If an earlier version does require updates, we go back to the version folder and make updates there.

We find the Zip Backup function very handy for our regular backups. Also, While there is a team of us working here, usually only one person is on a manual at a time. On the rare occasions when 2 people need to access the same manual, we just make sure we co-ordinate our efforts.

Thanks for so many good replies!

I have spoken to one of our software guys who said he can incorporate me (i.e., Flare work) into the source control system. We're going to use TFS because that's what the developers will be using shortly (but they're currently using SVN). I did suggest that SVN is another option available but one of our developers suggested that it would be better to have the user guide incorporated into the same branches and sections of source control as the version of the software it is related to. I like this idea because our software team aren't used to needing to update the user guides so this is also a good prompt for them to remember (that or I'll be on their heels asking for it).

That said, we haven't implemented TFS yet (but have just begun the process for implementation) so in the meantime I'll go with the manual source control -- I like the idea of Marjorie (Msquared) where I do a backup of the specific version of the user guide released. It won't really work should I need to update that version because then I'll have my different branches forming but in the meantime, it's a great and workable solution. Long-term, I think Nita Beck is onto something in the sense that doing the manual backups would not be sustainable (especially as I bring in someone else to help me use Flare).

So, the verdict... source control, here we come!

Thanks for so much good advice -- this forum has been so handy!

I know this isn't much help to the OP, but I'll say it anyway for the benefit of the thread and those who come after:

I have had a lot of success using a cloud SVN provider called CloudForge. I'm not affiliated, nor do I get anything for recommending them, but for people in small shops who just need to version control the documentation, this is a great solution.