Friday, February 13, 2015

Toot Toot the Horn

Nancy posted to the Techwr-L about numbering in snippets not working as expected within RoboHelp 11.

I replied with the following:
I haven't used RoboHelp in several years so this isn't a response that will solve your question within RoboHelp. Rather this is a response to the idea of including numbering within a snippet.
In the recent past, I ran into a similar issue with Confluence and snippets.
I was seeing the same type of thing you describe, where every step is step 1. That's when I said to myself, "Stop including "the number" within the snippet!" That was when it dawned on me that if I considered "the number of the step" to be 'formatting' and to make my snippets only be content - not including "the number" within the snippet - I could use the content in any situation.
In Confluence, the Wiki markup would have looked like this:
# {include:_navigation_one}
# {include:_navigation_two}
Where the text in the _navigation_one snippet = Go to Path 1 > Path 2 & the text in the _navigation_two snippet = Click , I would see
this:
1. Go to Path 1 > Path 2
2. Click [name_of_button].


Nancy wrote back:
Does your solution mean that I would need to make each individual step a separate snippet?

I wrote back:
Yes.
If it makes sense for your content.
For me, it did make sense for the content I work with on a daily basis. Navigation paths seem to be everywhere. What I quickly learned was that I was going to have the same navigation path on multiple pages. I also wanted to build in the flexibility that if the menu option “Project Mgmt” is changed to “Project Management”, I would simply change one snippet. This type of approach doesn’t have to be limited to navigation steps. Other elements, such as screen shots, notes & warnings, can be stored as a snippet and referenced as well.
I didn’t always think about the content like this – I had to be burned to figure it out. At a different company, “someone” decided it would be a “great” idea to add a new “Management” top-level menu option to the UI and then to move former top-level menu options “Widget Management” & “Foo Management” under it. Each first step had to be changed in multiple procedures. Vividly, I remember how that simple UI change caused hours of work for me. That’s why, whenever it makes sense, I create snippets and refer to the snippet instead of (essentially) hard coding text that is going to need to be repeated on more than one page. It doesn’t have to be a huge undertaking – I’ve created bookmarks within a Word doc and referred to the same text instead of copying/pasting that paragraph in a different part of the document. I can’t change that episode in my career, but I don’t have to watch the rerun!
Here’s a real world example of where I would use a snippet. Look at this page: http://geekstweaksweblog.blogspot.com/2013/02/protect-your-document-workbook-or.html. Search for “Important” and read the multiple variations of that text.
In the first paragraph: “It's important to know that if you don't remember your password Microsoft can’t retrieve your forgotten passwords.” There’s nothing about if the password is “lost”.
In the “Protect your Word document” section: “Important: Microsoft cannot retrieve lost or forgotten passwords, so keep a list of your passwords and corresponding file names in a safe place.”
In the “Protect your Excel worksheet” section: “Important Microsoft can’t retrieve lost or forgotten passwords, so keep a list of your passwords and corresponding file names in a safe place.” Notice there’s not a : after “Important” in this blurb.
In the “Protect your PowerPoint presentation” section: “Important Microsoft can’t retrieve lost or forgotten passwords, so keep a list of your passwords and corresponding file names in a safe place.” Notice there’s not a : after “Important” in this blurb.
The same concept explained 4 times on a single page. Not only that, but the concept is presented inconsistently. I would have created a single snippet for this concept and referred to it each time. If I decided there should be an icon instead of the word “Important”, I would have one change to make, not four. If a co-worker insisted upon changing “Microsoft can’t retrieve lost” to “Microsoft can’t retrieve your lost …”, the snippet is changed once; all 4 times are updated.
Again, all of this is applicable to the work I do on a daily basis and your mileage may vary.

No comments: