Today's feature request: snippet variables. Anyone else in?

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
Msquared
Propellus Maximus
Posts: 848
Joined: Mon Aug 06, 2012 10:19 am
Location: Southampton, UK

Today's feature request: snippet variables. Anyone else in?

Post by Msquared »

Something I've been meaning to ask for for ages. Anyone else want to second my proposition?

Here's what I wrote in my feature request.

Title: Ability to define snippet variables, that are set at the point the snippet is placed in a topic

I often have boilerplate text that needs to be repeated in many places (sometimes several times in the same topic), with one or two substituted values. My solution so far has been to either write the text generically, so it works anywhere, which sometimes reads badly, or extract the specific bit out to the main topic body, and leave the bulk of the content generic, which can then become a snippet.

Often, this compromises the quality of my content, so please could you provide a facility to specify a specific sort of variable, a snippet variable, which CANNOT BE SET AT TARGET LEVEL, but is defaulted when the snippet is created, and can be overwritten when the snippet is placed in a topic.

Recent examples where I really could have used this.

My installation guide has lots of similar instructions, some of which needs to be done on the Side A database server, and some on the Side B database server, and also on the Side A application server and also on the side B application server. Sometimes I can say

"On the Side A Database Server do the following:
<snippet follows>"

but sometimes that's a bit contrived, and for clarity, and to avoid errors in the installation process, I have to manually cut and paste the text, remembering to replace all instances of the server name with the appropriate one, and also, remembering to apply any subsequent changes everywhere the text is repeated. This increases the chances of errors in the document.

Or another example I've been struggling with today. This is what I want to say:

"To add a new supervisor, click xxx to see a list of possible supervisors. Select the supervisor you require. To filter the list, type a name or partial name in the search box, then click Search to see only the matching supervisors."

This is repeated multiple times, with various other items instead of "supervisor". I've already had to change the instructions twice because the developers changed the selection mechanism. I can't make the whole thing a snippet because of the "variable", which in this example, is set to "supervisor". But it could be any one of about 20 other items. So I decided to do a bodged snippet, and pull out the variable bit to the start of the sentence so the rest could be a snippet. Hence

"To add a new supervisor," <start snippet> click to see a list of possible choices for this field. Select the item you require. To filter the list, type a name or partial name in the search box, then click Search to see only the matching items. <end snippet>

So it reads;

"To add a new supervisor, click to see a list of possible choices for this field. Select the item you require. To filter the list, type a name or partial name in the search box, then click Search to see only the matching items."

I think you will agree that this isn't technical communication's finest hour and isn't particularly clear for the reader. Why call it an "item" when I called it a "supervisor" in the first sentence?

I have lots and lots of places where I use boilerplate text, and could really do with this. This would be true single sourcing.

Anyone with me on this?
Marjorie

My goal in life is to be as good a person as my dogs already think I am.
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Today's feature request: snippet variables. Anyone else in?

Post by doc_guy »

The solution here is something called snippet conditions.

You create a new condition tag set for your snippet conditions, and then you, for your example, would create conditions for each guide (one for Guide A, one for Guide B, etc.)

Then you create your snippet, and you apply the conditions to the content in the snippet itself.

Then you insert the snippet into a topic. Now right-click on the topic file itself in the Content Explorer, and go to Properties. There is a tab for snippet conditions. Select the include/exclude conditions for how the snippets should be used in this topic, and save.

Now go back to your topic. You see the snippet with just those conditions that match your settings for the topic. Go back to the snippet and you see that the other content is still in the snippet itself, it is just being excluded from this topic.

Make sure when you build your targets that you don't have any include or exclude settings for your snippet conditions at the target level, because you have controlled this at the topic level.
Paul Pehrson
My Blog

Image
Msquared
Propellus Maximus
Posts: 848
Joined: Mon Aug 06, 2012 10:19 am
Location: Southampton, UK

Re: Today's feature request: snippet variables. Anyone else in?

Post by Msquared »

I obviously didn't make my self clear. Sorry! Snippet conditions won't be suitable at all, for lots of reasons.

Consider a really simple example, I'd like to say ""To add a new xxx, click Show to see a list of possible xxxs. Select the xxx you require. To filter the list, type a name or partial name in the search box, then click Search to see only the matching xxxs." There may be twenty or thirty different possibilities for xxx, and several of them may need to appear in a single topic (perhaps these are field-level descriptions, and each dialog box may contain several such fields).

Snippet conditions aren't suitable for lots of reasons. I do use them when appropriate, but reluctantly, as I think the implementation is flawed and not flexible enough, and it's easy to get confused and cause a maintenance headache for subsequent writers.

1. You apply snippet conditions at the topic level (the wrong implementation, I think) not at the point where the snippet is placed in a topic (the correct implementation, I'd say), so I could only have one distinct value for xxx in a topic. For a field level description, I may need to reuse the same snippet several times with different values for each. For this reason alone, I couldn't use snippet conditions, even if they were otherwise the correct solution (which they're not in this case).

2. With 20 or more possible values for xxx and hence the same number of snippet conditions for this snippet alone, the snippet and the condition set would get very messy very quickly, and hence unmaintainable in the future. This is only one instance of one snippet. If I truly single-sourced all my boiler plate text, I'd have dozens of different snippets, each potentially with their own corresponding set of conditions.

3. If I need to add a new value for a possible xxx to the existing set of xxxs, I'll need to modify every single snippet where this set of xxxs apply, and (nightmare of nightmares) every single topic where this snippet is already placed to exclude this new snippet condition in that topic for each existing placement. I may miss a few (dozen, probably).

4. What will translators make of it for languages where some xxx may be masculine, feminine or neuter, for example, and where this affects the wording of the snippet? Even if they know these snippets exist, they will have some messy investigation and even more messy fixing to do if snippet conditions are used. If snippet variables were supported, then I, as a helpful author, would give them a list of all the snippets that use variables, and they would then be easily able to see what value for the variable was used in each placement. They could then translate my single snippet into as many different variants as required for different genders etc, and use the correct one in each place. Or they could easily add another variable or two to the snippet to reflect the different phrasing required (I would need to do one or other of these myself for boilerplate text where the plural of xxx wasn't xxxs, but xxxes say).

So that's why I want snippet variables, because snippet conditions won't do for this scenario, and that's why I want to be able to set the value of the variable at the point where the snippet is placed in the topic, not as an attribute of the topic. I can't be the only person who wants to do this to simplify my content, surely?

Coming back to snippet conditions (which I'm about to raise a separate enhancement request for). I think the idea is good, but the implementation is wrong, which makes them confusing and error-prone in use, and far less useful than they could be.

Firstly, I think they should be a completely separate type of condition - they shouldn't be able to be set at the target level, as if this is done by mistake, it can override the snippet condition set at the topic level, and hence what the original author intended. This makes subsequent maintenance a problem.

Secondly, I think the condition that applies to them should be set when the snippet is placed in the topic, not on the topic itself. This will allow you to reuse the same snippet twice in the same topic with different conditions applied.

For example, my installation guide describes several different installation configurations (single server running everything, multiple servers running everything, multiple servers each running various components, duplicated servers running redundant copies etc) depending on the customer needs. So I have topics that describe the steps to take for each configuration. Many of these steps will be identical, but some will not apply to all configurations. I can easily write one snippet with snippet conditions so the snippet can be used for any configuration. But because I have to choose the snippet conditions to apply at the topic level, I cannot put this snippet more than once in the same topic with different conditions (for example, if I want to write one topic that provides instructions for several installation configurations). So I can't decompose my content into topics according to best content practice - I'm restricted by Flare's snippet condition implementation.
Marjorie

My goal in life is to be as good a person as my dogs already think I am.
btwrites
Propeller Head
Posts: 20
Joined: Mon Aug 19, 2013 12:31 pm

Re: Today's feature request: snippet variables. Anyone else in?

Post by btwrites »

Yes, Marjorie I am WITH you! 100 percent. All of your points are valid. I'm starting to run across this issue in my Online User Guide. I was trying to address it with Variables, but also noticed (at least I haven't figured it out yet - I'm fairly new to this) that you can't do a lot of formatting with variables - say, numbered and bulleted lists, etc. I think Snippet Variables is a good solution and I think it ought to be a feature request.
paul_collins
Propeller Head
Posts: 22
Joined: Thu May 22, 2014 7:25 am

Re: Today's feature request: snippet variables. Anyone else in?

Post by paul_collins »

Count me in. Snippet variables would be very useful and far easier for other authors to maintain and understand.
SteveS
Senior Propellus Maximus
Posts: 2087
Joined: Tue Mar 07, 2006 5:06 pm
Location: Adelaide, far side of the world ( 34°56'0.78\"S 138°46'44.28\"E).
Contact:

Re: Today's feature request: snippet variables. Anyone else in?

Post by SteveS »

Don't forget, this isn't the place to lodge enhancement requests!

If you have an idea it can be lodged at https://www.madcapsoftware.com/feedback ... quest.aspx

Merry Christmas, everyone :D
Image
Steve
Life's too short for bad coffee, bad chocolate, and bad red wine.
lise
Propeller Head
Posts: 35
Joined: Tue Mar 24, 2015 12:45 pm

Re: Today's feature request: snippet variables. Anyone else

Post by lise »

Msquared wrote:Snippet conditions aren't suitable for lots of reasons. [...]

1. You apply snippet conditions at the topic level (the wrong implementation, I think) not at the point where the snippet is placed in a topic (the correct implementation, I'd say), so I could only have one distinct value for xxx in a topic. For a field level description, I may need to reuse the same snippet several times with different values for each. For this reason alone, I couldn't use snippet conditions, even if they were otherwise the correct solution (which they're not in this case).
This is exactly what I need. I spent all of yesterday creating a great compact snippet that could be used for multiple topics and it worked like a charm within each topic but the minute I tried using more than one in the same topic I discovered I couldn't do it. I was heartbroken.

I definitely vote for an option to apply snippet conditions at the point where it is placed in the topic rather than the topic level.
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: Today's feature request: snippet variables. Anyone else

Post by ChoccieMuffin »

@lise, in that case put in a feature request. The more people who do, the more likely it'll get into future products. See my footer for the request link.
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
lise
Propeller Head
Posts: 35
Joined: Tue Mar 24, 2015 12:45 pm

Re: Today's feature request: snippet variables. Anyone else

Post by lise »

ChoccieMuffin wrote:@lise, in that case put in a feature request. The more people who do, the more likely it'll get into future products. See my footer for the request link.
Done.
Post Reply