Multiple version management: am I missing something?

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
gwk
Jr. Propeller Head
Posts: 3
Joined: Mon Jan 05, 2015 6:03 am

Multiple version management: am I missing something?

Post by gwk »

Hi there,
I'm new to Flare and am checking it out with a view to migration in the next few months.

My question is this: can I put in place a sensible strategy for maintaining multiple versions of a single product's documentation at once using Flare?

Here are my requirements and assumptions:
  • Each version represents a different release of the software product, e.g. 1.0, 1.2, 2.0 or 5.0R3.
    I must maintain multiple versions of a single set of topics, one per product release. The number of product releases may be upwards of 5, and this number will grow.
    I will be publishing to flat HTML files, web help and PDFs, all of which must be available - profiled for the distinct product releases.
    I want to maintain true single-sourcing, and I don't want to create parallel topics for each product release (unless it's the only way)
    At any time, I want to be able to build the docs set for any given product release.
    The extent of variation between product releases may be as simple as nouns changing, right up to large sections being added to topics. ToCs may change between product releases.
It seems like a few people have asked about this kind of thing before (see http://forums.madcapsoftware.com/viewto ... 75&t=19497 and http://forums.madcapsoftware.com/viewto ... le#p104571). The recommended solution seems to be conditional tagging, however I can see that that solution will not scale easily to many versions.

I can't see any recommendations in the MadCap manuals, and I wonder what people are doing in this area.

It's also worth saying that if at all possible, I would rather avoid using SCM tags to mark product releases. If I did this, I wouldn't be able to go back and update tagged versions later.

All ideas and experiences appreciated :)

Thanks,

Graeme
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: Multiple version management: am I missing something?

Post by RamonS »

My experience is that sunsetting versions is the only option. While there are many valid cases to be made for keeping old versions around and maintained it is in the end a struggle that neither scales nor provides much benefit. I assume that it is not your choice to keep that many versions around, but the lack of procedures is testament to this being a product management issue and management issues cannot be fixed by software. Keeping that many versions current is not only a problem for docs, but for development, QA, support, and sales.
Most software companies support only the current version and the one before, or they set EOL dates upfront (e.g. Microsoft). Maintaining every release indefinitely just doesn't pan out.
benjimenez
Propeller Head
Posts: 78
Joined: Mon Aug 30, 2010 4:17 pm

Re: Multiple version management: am I missing something?

Post by benjimenez »

First, thank you (and others) for posting this thread and similar threads and confirming my own concerns. I agree with RamonS but still have to find some approach.

My existing "strategy" is kind of a hybrid of conditional tagging and separate Flare projects. Admittedly, it's not the ideal practice IMO, but it will have to do for now. That is, I have one Flare project for every major release and use conditional tagging for minor and maintenance releases.
Niels
Propeller Head
Posts: 89
Joined: Thu Dec 15, 2016 8:41 am
Location: Köln

Re: Multiple version management: am I missing something?

Post by Niels »

We are starting right now with an attempt to manage at least two close release versions (that formally require their own documentation set) within one Flare project by a "lazy split" strategy based on sub-folders and splitting a Flare resource only when it becomes necessary. This should also work in a group with many authors (we are only two) if everyone sticks to some basic rules. Our central process steps in a nutshell, where 981 indicates our previous release version:

Before starting with an edit that requires to preserve a resource for 981:
  • Copy this item to the 981 subfolder (and rename with the suffix _981).
  • Replace the trunk element in the 981 TOC by this copied element. (On level 1 don't forget to set "Chapter Break".)
An image split has to be done in the same way:
  • Copy the image to a new 981 subfolder in the image folder.
  • Replace the trunk image in the 981 topic file by this copied element.
This leaves us with a few one-time preparations for a minimum of elements that require a split. A split is just a copy with a rename and some adjustments, e.g. a dedicated destination path for the old release version. (We are publishing PDFs in an SVN environment.)
  • Add a new publishing destination for 981 with adjusted path
  • Split TOC
  • Split Target (also to be able to set different status variables in here for version, author and publishing date)
  • Split our topic file Applicable Documents (in our case always required since we cross-reference version-specific sources like a compatibility guide)
We follow one convention to easier identify split topics in the old release version TOC: Rename and add a versions suffix to the copied resource (like an image or a topic file used in everyday updates, and required one-time only for the each new target/toc/destination).

I think we could still consider conditional text in here, but the whole approach is actually not based on any specific Flare functionality other than being able to use different TOCs which can point to different split version resources but which can also share the same topic files where this is still applicable.

Maybe this can inspire someone, otherwise we are open for any feedback on risks or drawbacks that you may see in this approach.
Niels
Propeller Head
Posts: 89
Joined: Thu Dec 15, 2016 8:41 am
Location: Köln

Re: Multiple version management: am I missing something?

Post by Niels »

Cross-references could pose an issue in theory and we get many compiler warnings, however, in practice in a generated PDF for us they still work as desired, although we do not have any clue why.
Does anyone understand what is happening inside Flare in a scenario as depicted in the attached presentation?
You do not have the required permissions to view the files attached to this post.
Niels
Propeller Head
Posts: 89
Joined: Thu Dec 15, 2016 8:41 am
Location: Köln

Re: Multiple version management: am I missing something?

Post by Niels »

I think I was enlightened and it is so simple:
  • Flare just looks for the bookmark in all topic files that are linked from the TOC of the current target
  • Since we have just copied the topic file in a split, the bookmark stays the same
  • By design we never include two topic files that were split in one TOC, so there is no conflict with identical bookmarks
Copying and renaming a topic file for a split still can cause issues, and cross-references or references to style sheet resources must be checked manually for split topics.
Post Reply