Best practice/workflow for tying changes to product version

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
mwright123
Propeller Head
Posts: 29
Joined: Tue Jun 21, 2016 4:32 am

Best practice/workflow for tying changes to product version

Post by mwright123 »

Hello,

Can someone recommend a best practice/workflow for tying changes to product versions?

For example, assume I am working in an Agile environment, and I am working on 3 feature changes in a given sprint. If 2 feature changes are released but 3rd is deferred for some reason, I need the ability to suppress the changes due to the 3rd feature change.

Is it best to do this via condition tags? Are there alternatives?

Is there a way to quickly "clean up" those condition tags after they are no longer needed?

Thank you!
Mary
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Best practice/workflow for tying changes to product vers

Post by NorthEast »

We have a similar challenge, and use conditions to mark the content for each feature.

No, there isn't an easy way to remove old conditions; it's a manual slog to remove any tags in Flare (unless you know how to strip out tags using regex in Flare's find and replace, or an external tool).
mwright123
Propeller Head
Posts: 29
Joined: Tue Jun 21, 2016 4:32 am

Re: Best practice/workflow for tying changes to product vers

Post by mwright123 »

Thank you for the reply, David! That is what I imagined might be the case.

Cheers,
Mary
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Best practice/workflow for tying changes to product vers

Post by Psider »

One thing I've done, rather than tag for specific releases is use CurrentRelease and NextRelease conditions.

As I make changes to an area, I tag the existing text that is going to change as CurrentRelease (sometimes this means duplicating paragraphs if a lot of small changes are being made in a paragraph) and my new/changed content as NextRelease. While I'm working it generally becomes clear what is definitely in and I delete the text tagged with CurrentRelease and remove the NextRelease tag from that content as I'm revising/editing.

My Production output excludes NextRelease, while my Test/Review output excludes CurrentRelease.

Anything that isn't ready won't get included in the production build because it's tagged as NextRelease. It's fairly quick to remove as you're applying review edits and you don't end up with a huge bunch of legacy tags - you should only have stuff held off for one release or so.

(I tried version numbers at one point, but it was a nightmare managing.)

e.g.
The quick [currentrelease]red[/endtag][nextrelease]brown[/endtag] fox jumps over the [currentrelease]rabid[/endtag][nextrelease]lazy[/endtag] dog.

Prod version: The quick red fox jumps over the rabid dog.
Review version: The quick brown fox jumps over the lazy dog.
mwright123
Propeller Head
Posts: 29
Joined: Tue Jun 21, 2016 4:32 am

Re: Best practice/workflow for tying changes to product vers

Post by mwright123 »

Psider, thank you for this reply - I will absolutely pass this along!

Cheers,
Mary
Jason MTL
Jr. Propeller Head
Posts: 4
Joined: Fri Oct 14, 2016 7:33 am

Re: Best practice/workflow for tying changes to product vers

Post by Jason MTL »

Greetings!

I'm working with Mary (mwright123) to try and find a new documentation tool that meets both our needs. We have a potential solution, and we hope you can provide some feedback.

Individually tagging changes would be nearly impossible for us. The additional work involved with tagging all changes would be unmanageable. Each feature could involve dozens of changes, large and small, and we deal with over a dozen new features every four weeks (using the Agile/Scrum methodology).

While talking to one of our software developers, it was suggested that we could treat the documentation source files the same as code source files. I believe I heard that Flare saves its content in XML files, correct? If so, then we may be able to set up a developer's structure where we can check out core source files, make the necessary changes for a feature, and then shelve the changes until we have confirmation that the feature will be included in the next release. The checkin process would automatically validate both the edited files and the core files, and merge the changes. The documentation outputs would then be generated from the core files. The question is whether or not Flare is capable of working like this.

I will be contacting MadCap Sales to see if they think it will work, but I would also appreciate feedback from users such as yourselves.

Thank you,
Jason
GregStenhouse
Sr. Propeller Head
Posts: 330
Joined: Tue May 13, 2008 3:27 pm
Location: Christchurch, New Zealand

Re: Best practice/workflow for tying changes to product vers

Post by GregStenhouse »

Flare does work with Source Control (SVN, Git etc), however there are no branching, merging or tagging options from within the Flare GUI. So you could treat documentation source files as code, but if you need to branch for sprints then merge back at the end, you'll need to use third-party tools like TortoiseSVN and BeyondCompare. It may be a valid approach though - writers working in sprints could bind their Flare project to a branch URL, then perhaps one or two users might have multiple branches and master and handle the merging. I'd recommend good processes around commit messages (e.g. enter the feature name or code and sprint number with each commit) if you go down that track.

However due to merge pain (especially if writers are not familiar with source control tools) using conditional tags in Flare with CurrentRelease and NextRelease may well be the way to go. As an example, just opening a topic and saving can generate changes to the html tag data, which can then lead to conflicts when multiple writers are also looking at that topic.

FWIW we are using SVN and maintain a master only - although we do intend to at least tag releases so we can go back and make changes retrospectively if needed.
Jason MTL
Jr. Propeller Head
Posts: 4
Joined: Fri Oct 14, 2016 7:33 am

Re: Best practice/workflow for tying changes to product vers

Post by Jason MTL »

Thanks Greg.

This isn't about old version vs new version. Changes for individual features within the same version must be kept separate from each other in order to keep some but not others. So each feature would need a unique tag, even if the feature is just renaming a field. That's a couple of dozen new tags every four weeks. With hundreds of changes, each tagged, many needing to have the original content maintained and tagged as "original", most of which having to be removed after publishing... I'm looking for anything that will spare me that pain. And alcohol isn't getting the job done. :)

From what I understand, the TFS source control would handle the branches and merges, and we may even be using the same branches created by the developers. There should only be merge conflicts when two writers change the exact same text for two different features, which should be uncommon, and it will be their responsibility to sort it out.

The question is whether Flare is flexible enough to allow an outside system to manipulate its source files. I would hope that Flare just sees a pile of source files that it needs to process when generating output, and doesn't care what happened to them in the last four weeks.

Maybe this won't work, leaving us with tags as the only remaining option. But I want to try, because this could be the cleanest solution if it works. It may even open new doors for procedurally generated content and other funky stuff. Oh, the possibilities! :)

Cheers!
Jason
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Best practice/workflow for tying changes to product vers

Post by Psider »

I've made changes to Flare htm files using TextCrawler before and Flare works fine with that sort of thing. Extra care would be needed with the Flare admin files to make sure you don't bork the syntax, but it *should* be fine to modify outside Flare. And I've done manual merging on htm files using BeyondCompare in Robohelp projects, which is far less forgiving due to its Access database.

I've never tried the (semi) automated approach used by developers, partly because years ago when I tried, RH made so many changes just by looking at a topic that it was a nightmare.

As always, try it on a test project, not your live one. :)

And post back with how you go. I'm sure there are a number of people who would be interested in your results.
Jason MTL
Jr. Propeller Head
Posts: 4
Joined: Fri Oct 14, 2016 7:33 am

Re: Best practice/workflow for tying changes to product vers

Post by Jason MTL »

Another user asked for an update on the integration, but the forum would not let me reply.

We are in the middle of testing Flare, but we are blocked by the import from Doc-To-Help not working (Support case in progress). However, our TFS administrators have done their own research and are very confident it will work. I will post an update when (if) we get it working.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Best practice/workflow for tying changes to product vers

Post by Nita Beck »

Jason MTL wrote:Another user asked for an update on the integration, but the forum would not let me reply.
Jason, you're still in the "moderation" phase given that you're a new forum user, so all of your posts need to be explicitly approved by a moderator aka MVP or MadCap person. I don't know what the threshold is, but after a while, you'll be able to post immediately.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
Jason MTL
Jr. Propeller Head
Posts: 4
Joined: Fri Oct 14, 2016 7:33 am

Re: Best practice/workflow for tying changes to product vers

Post by Jason MTL »

Hi Nita.

I meant that I was sent a PM, but I did not have any options to reply to the PM or create a new PM. I just checked again, and now I have reply options, but they weren't there this morning. Strange.

Thanks,
Jason
Post Reply