Recommendations on managing revision history

[jkpalmer]

Hi,

We are going to use Flare for managing requirements documentation.

We would like to be able to be able to have the revision history present in a topic and then the revision number(s) embedded in the remaining topics at the location where that revision too place.

Has anyone ever done something like this in Flare and is there a good solution that can be implemented in Flare or is it pretty much a manual effort?

TIA

Jim P.

[TechOnTheBrain]

Did you ever figure this one out? I'd be interested to know how you solved it.

[jkpalmer]

Hi,

Still working on this. I think it is going to come down to establishing and enforcing some "business practices" for contributors and flare administrators.
My thinking is that when changing content, the "old" content should be preserved and marked with a conditional tag (like OldContent) and the "new" content is added/updated with significant annotations.
The Flare Admin would then generate a report to get annotations and include that report as part of the "general published content".

I would like all of this to happen "auto-magically" but will settle on doing manually for now.

I would love to see Analyzer have the ability to produce CSV output but the architecture seems to allow for the generation of multiple outputs within a single generated report result.

Still working on the process and making sure that it is feasible, meaningful and manageable.

JP

[TechOnTheBrain]

I might be missing your point, but surely no special processes and effort are needed to archive and manage the content itself since source control does that for you? (Unless you're not using source control?)

Managing version history of the content and/or targets though... this does seem to be tricky, or at least good ways to do it are not obvious to me.

[cruitbuck]

Flare is not a project management tool. Never intended to be. You are asking an apple to be an orange. Both grow on trees, are fruit of some sort, and are food. But they are different in complex ways. You are asking for trouble trying to force Flare into some role it is not intended to do. Manage your requirements and PM docs in TFS or some other product suitable for project managers. Flare Admin? We're all tech writers here. If there is a Flare Admin, please stand up.

Bob the Tech Writer

[jkpalmer]

The requirements that our business would like to see implemented in Flare publications is fairly straight forward (from the business perspective), but from a Flare implementation, there are some challenges.

For the sake of this discussion, there are two targets:

1) Standard - which will only display the current and necessary information to the "standard" viewer.

2) Historical - which will display a more comprehensive document with original and revised content - our challenge.

We're not looking for a project management tool but for someone's technique on how they may have captured "before and after" information and made it accessible to those who need it (the historical viewer/reader).

We believe that we have a strategy that will work for us. It will require some extra work and manual processing, but the bottom line is the business needs to be satisfied with the published outcome and that is our (my) mission.

When we think we've got it figured out, or when we've seen the error in our ways, I'll share.

Appreciate everyone's input.

Regards,

Jim P.

[ChoccieMuffin]

Conditions, I suspect.

Create two conditions in your condition set: Historical and Standard.

In your topics, set the condition for any content that might change in later, or isn't needed in the Standard version, as "Historical".
When creating the Standard version, when you add new content condition it as "Standard".
Etc

Create two targets - one for Standard, one for Historical.

For your target output for the Historical version, don't exclude any conditions.
For the target output for the Standard version, exclude "Historical".

If you want the Historical version to include some kind of colouring to show which is which, you'll have to set up a style for each condition (e.g. "Historical" with a pink background, "Standard" with a blue background, I suggest using generic styles) and also apply the styles to the stuff to which you've applied the conditions. (Except if it's HTML5).

If you don't want your Standard version to also display the background colour you'll need to include another medium that has the "Standard" style with background colour not set.

That approach could get messy if you want to create Version 2 of Standard but you want to keep a record of what was in Version 1 as well as Version 2 in the Historical version. I won't go down that route in this suggestion for the moment, but if you do you'll need to add more conditions and another style.

[jkpalmer]

Interesting approach, Choccie.

The business users are conflicted on what they want.

I've been thinking about "requiring" the use of annotations, when a change is made to a topic, using the annotation as a "source" of Historical content, i.e. receive the revised topic (with track changes on) and taking the annotation that would be required for any change, and insert that as "Historical" comments/content (tagged).

Any changes without an annotation would be returned to the reviewer for their annotations.

Another option that I've been tossing around is using the Files With Annotations report and summarizing all the annotations in a separate topic (like Revision History), possibly with bookmarks to the changed topics. I need to build a conceptual model and present to the business.

Both are a little busy, but either might work.

Thoughts anyone?

Jim P.