How to tell if a shared snippet was updated

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
MikeJasper
Jr. Propeller Head
Posts: 7
Joined: Fri Apr 07, 2017 9:53 am

How to tell if a shared snippet was updated

Post by MikeJasper »

We have a customer that wants us to update a "change log" at the beginning of the PDF version of their doc that lists any changes to the manual and when they were made.

The customer uses a customized version of our Installing/Configuring manual, so 90% of the manual can use snippets from our existing Installing and Config topics.

Here's the question: Is there a way for me to tell in Flare when a shared snippet has been updated outside of this customer's book (so I can update the change log for that customer)?

We have 4 writers on our team, so content gets updated all the time in the various snippets.

The other option is to NOT use snippets and maintain 2 versions of the same docs... Not fun.

Thanks!
Mike Jasper
Senior Documentation Specialist, ScienceLogic
roboHAL
Sr. Propeller Head
Posts: 254
Joined: Mon Dec 31, 2012 9:57 am

Re: How to tell if a shared snippet was updated

Post by roboHAL »

Hi Mike -

I'm not completely sure what you mean by a shared snippet. In any event, to my knowledge flare only "knows" when a topic or snippet has been revised based on Windows (or other OS) modified date attribute. For instance, Flare does read the date modified information and displays it in the file explorer. If you are using 4 authors and are using some kind of source control, the plot thickens even further as different types of source control "handle" modified dates differently. (i.e. the same file modified on a particular date can be retrieved by more than one author and the date can read differently.

This is one (of the only, as Flare is far superior) advantages of Zendesk. Each time an article is modified, the modified date displays in the article.

Back to Flare.... you can try and use some kind of variable as a possible solution and/or java script. I have, and it didn't really work out that well.

Frankly, I *think* the only solution is to include a field (or other provision) in each topic and/or snippet which is manually updated by the help author.

But I would be interested to read what any others who have been successful have to add.

Best of luck :|
MikeJasper
Jr. Propeller Head
Posts: 7
Joined: Fri Apr 07, 2017 9:53 am

Re: How to tell if a shared snippet was updated

Post by MikeJasper »

Thanks for the response, roboHAL.

By "shared snippet" I meant that we often reuse the same snippet in 2-3 books.

So there's our big Install guide, which includes the basics of installation. All of those Install topics are in snippets.

Then we have a couple other books that use the basic Install snippets, but we surround it with some custom info as needed (for a custom install of our product).

So we share those basic Install snippets across a couple books, so it'd be nice to know when someone updated a snippet from the big Install guide, because that snippet is in 2-3 other custom Install books.

We were wondering if there's a Flare feature that tracks those changes...
Mike Jasper
Senior Documentation Specialist, ScienceLogic
roboHAL
Sr. Propeller Head
Posts: 254
Joined: Mon Dec 31, 2012 9:57 am

Re: How to tell if a shared snippet was updated

Post by roboHAL »

You're welcome Mike.

Okay, so your "shared snippet" I would call/label a "common snippet". No matter, I understand.

Your shared snippet should only be *editable at the source* (i.e. the help author in the Flare environment). Once that shared snippet appears in your basic, custom and other install guides, the snippet has now made its way to the *output*. There should be no change made to the snippet as it appears in the output by any of the recipients/readers/users of that output.

If what you are stating is that (hypothetical) a recipients/reader/user of one of the outputs - say custom - communicates certain changes back to you (the help author), asks that you introduce those changes in the source, you comply/implement the changes, and then another user - say basic - wants to understand what edits the custom user had you introduce, then I'll stick to my previous post and suggest the inclusion of a field (or revision section) in each topic and/or snippet which is *manually updated* to specify what those edits were.

The aforementioned said, there probably is some third party software that can do a file comparison of before/after and display the delta (similar to team foundation server visual studio source control). I don't even know if that would help, because it would be outside of Flare. I'm at a loss as to what else to suggest. If I've again misunderstood your intention, by all means let me know.
MikeJasper
Jr. Propeller Head
Posts: 7
Joined: Fri Apr 07, 2017 9:53 am

Re: How to tell if a shared snippet was updated

Post by MikeJasper »

Thanks again, roboHal! I appreciate your time and insight. I'll keep looking for a good method for tracking updates, either within Flare or another tool.

Guess my team will just have to communicate with each other (what a concept). :wink:
Mike Jasper
Senior Documentation Specialist, ScienceLogic
roboHAL
Sr. Propeller Head
Posts: 254
Joined: Mon Dec 31, 2012 9:57 am

Re: How to tell if a shared snippet was updated

Post by roboHAL »

You're welcome again Mike.

Something else you may find helpful to know (if you don't already) :)

If all you are wanting to know is **if** the snippet was updated - irrespective of what the update entailed - you can use the file tag set feature of flare. Perhaps this is all you need because the title of this thread "How to tell if a shared snippet was updated" implies you are merely looking for a "flag" of sorts.

So, if you create a tag labeled (for example, it can be anything unique) "revised_snippet", whenever you change the content of the snippet, you could set (select, check) this flag. Afterwards, you can run a report that includes file tags and provide that report in your various outputs. Granted, this is still a manual process of setting the flag and a manual process for the end user to open/view the report, but it wouldn't involve anything "third-party". :D
MikeJasper
Jr. Propeller Head
Posts: 7
Joined: Fri Apr 07, 2017 9:53 am

Re: How to tell if a shared snippet was updated

Post by MikeJasper »

I'm going to look into the concept of using tags - thanks again for the tips!

Right now we're just adding an all-new Conditional Text sentence at the top of each snippet that contains text saying "This snippet is shared with the XYZ manual. If you update it, update the Change Control page in the XYZ manual (or contact Mike)." :)

Not elegant or automated, but relatively painless...
Mike Jasper
Senior Documentation Specialist, ScienceLogic
Post Reply