Today's feature request: snippet variables. Anyone else in?
Posted: Tue Jun 10, 2014 11:39 am
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?
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?