Any clever way to compare 'now' with 'last published'?

[TechOnTheBrain]

I'm looking for ways to make it easier to manage version history for multiple targets. Given single-sourcing, it is very easy for a significant change to affect multiple targets, but it seems hard to compile a version history for the target in a way that is reliably accurate and not too onerous.

To make one possible approach a little easier, I wonder if anyone knows a quick and easy way to do the following?

• Compare the content that went into a target the last time it was 'published' with the 'current' content that is near to being published. The idea is that this comparison could be used as a reference whilst the author updates the document/version history for the new version that is about to be published. Repeat for every target that is about to be published as a new document version.

In the absence of a better idea I think this would be an aid to both speed and accuracy during the tedious job of updating document histories, where they are required. Especially given the added potential for oversights when single-sourcing pushes a change into multiple targets whose history we might otherwise forget to update.

Can something like this be done with Flare? Or perhaps with Analyser?

[Nita Beck]

Maybe a folder/file compare tool, something like Beyond Compare? Compare fresh output to a prior published output?

[techwriter31]

Maybe a folder/file compare tool, something like Beyond Compare? Compare fresh output to a prior published output?

We use Beyond Compare for this type of thing. You can also compare PDF outputs (at least for English and European languages...Japanese, Korean and Chinese not so much. ) It's useful to provide reviewers with the comparison report too, so they can quickly see what's changed between revisions. We also use folder/file comparisons for larger projects, to determine the new/modified files to send for localization.

[TechOnTheBrain]

Interesting tool, thanks - I hadn't heard of Beyond Compare before.

It does seem like an interesting option as a work-around for some situations. But I'm rather hoping there is a way to achieve my ends within the authoring environment, rather than another work-flow in another external tool with another set of caveats to manage (e.g. if you're comparing PDFs it won't flag any changed images, which could be significant for the version history).

But perhaps, like many other tools, there just isn't a sensible way to keep an accurate version history going in Flare targets? (At least not without heavy reliance on special manual effort and hyper-awareness on part of the authors)

I can't help thinking that I'm missing something and that it should somehow be much easier than it appears to confidently manage accurate version histories across many targets in a single-source project.

Though perhaps I am being a bit of a 'noob' and missing something basic. Kellie, you said that you give reviewers a comparison report and do similar for localisation - how exactly do you do this? In particular, how do you retrieve the correct 'old' versions of Flare files from a previous version for comparison with latest work?

[techwriter31]

In particular, how do you retrieve the correct 'old' versions of Flare files from a previous version for comparison with latest work?

We use version control for our source files and create tags and branches. We can then compare two branches to diff the source files. We also have an archive for the outputs and can use these archives to diff the outputs.

[Nita Beck]

We use version control for our source files and create tags and branches. We can then compare two branches to diff the source files. We also have an archive for the outputs and can use these archives to diff the outputs.

My clients and I do exactly the same thing re tags and branches, as well as about archiving the outputs. (But we haven't done diffs, not having had the need. But if we did, I'd recommend Beyond Compare to them.)

[TechOnTheBrain]

Ah, interesting. I've been using Git source control, but haven't really experimented with branches yet.

At the risk of sounding dumb, how do you work with this? I can see how comparing 'previous' and 'current' branches will help you identify differences that might need to be highlighted in version history (or histories, where multiple targets are involved). But:

• When do you create a branch, on what basis?
• What tags do you apply to what things as far as document versions are concerned?
• How do you compare content for individual targets rather than the entire branch?
• How do you 'archive' your branches? Or do you only archive the outputs, in which case aren't they much more fiddly to compare than the source?

I hope I'm not being too dense. All advice appreciated.

[MattyQ]

• When do you create a branch, on what basis?
• What tags do you apply to what things as far as document versions are concerned?
• How do you compare content for individual targets rather than the entire branch?
• How do you 'archive' your branches? Or do you only archive the outputs, in which case aren't they much more fiddly to compare than the source?

I hope I'm not being too dense. All advice appreciated.

I am super interested in answers to these questions, too! We've had some discussion of branching with Git, and I'm really curious how others handle it.

[Nita Beck]

For a nice overview of the source control concepts of "branches" and "tags", this little article is really nice: http://betterexplained.com/articles/a-v ... n-control/. It's SVN-centric, but the concepts can be applied to Git. The most important thing to understand about the term "tag" is that it has NOTHING to do with tagging anything in Flare. Rather, a source-control "tag" is a named point in time at which one wants to preserve a collection of files.

My co-authors and I always commit our changes to the "trunk" (SVN) or push our commits to the "master" (Git). But when we have come to the end of a release cycle, say 1.0, then we create a tag called "1.0". That way, if we ever need to go back to the Flare project as it existed at that point in time, we've got that named point in time.

In my own practice, we rarely create branches. Just haven't had the need. The few times we have created branches, some of them ended up being abandoned (their changes not merged back into the trunk), while others did get merged back in. But I know that there are users here on the forums who use branching all the time.

There have been lots of discussions on the forums here about branching, tagging, etc. Also, the Better Explained guy also has an article, albeit geeky, on Git: http://betterexplained.com/articles/aha ... rning-git/ and another on the general concept of distributed version control, which is what Git is: http://betterexplained.com/articles/int ... lustrated/.

[techwriter31]

We also use SVN (but don't use the Flare integration to bind our projects to source control). We work exclusively on branches, as we tend to have concurrent software releases. Each branch represents a software release and the work for that release is done exclusively on the branch. We localize our content post-release and create branches for this localization work as well, as we may have several concurrent localization projects for the various releases. Like Nita, once the release or translation work is complete, a tag is created. The branch is then merged back to trunk and to any subsequent branches.

We use TeamCity to build our Flare outputs on each branch and package the files for the appropriate software installers. We also use it to publish the outputs to our documentation archive, which is made available as an internal website that provides links to the documentation for all software releases and post-release localizations.

[TechOnTheBrain]

Nita, Kellie - thank you both, I'll have a look at those ideas and see how I get on!

[TechOnTheBrain]

Okay, I had a look at the links Nita posted. I pretty much get all of that, at least in outline. But I'm no further ahead in outstanding how to actually take advantage of it in my Flare projects in practice.

Sure, I can create branches in Flare 11 - but how do I do this Git tagging business? Or is that bit not included in the built-in Git client with Flare? Any solution that involves other stuff outside Flare is far from desirable - even if I can manage it, a client is unlikely to.

This all seems terribly complicated, or at least obscure. I think I understand source control basics - I just don't see how to use it to help me compile version histories reliably and reasonably painlessly.

[Dee Vincent-Day]

I too would be interested in knowing more about this. I can only access my content through the Flare API. I am not able to log into Git directly to use any of the features such as tagging. Git compare looks really useful.