TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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!
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.
From: Nancy Allison [mailto:maker -at- verizon -dot- net]
Sent: Friday, February 13, 2015 10:45 AM
To: twer_lists_all -at- hotmail -dot- com; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: RE: [RMX:NL] HELP! RoboHelp numbering in snippets
So, Paul, does your solution mean that I would need to make each individual step a separate snippet?
On 02/13/15, Paul Hanson<twer_lists_all -at- hotmail -dot- com <mailto:twer_lists_all -at- hotmail -dot- com> > wrote:
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 <name_of_button>, I would see
this:
1. Go to Path 1 > Path 2
2. Click <name_of_button>.
I
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy & Procedure Guides, eBooks, and more using Microsoft Word | http://bit.ly/doctohelp2015
