Editor's Note: On Monday, 5-1-2023, I moved work-related information to https://prhmusic.blogspot.com/p/single-sourcing-rant-work-related.html
The Magic Semi Wheel
Single sourcing is a buzzword among technical writers. It is one of my soapbox topics. When I get up on my soapbox, I think about a magic wheel on a semi trailer and my mind starts imagining...
What if you had a semi with 18 wheels on it and you needed to change all 18 tires?
Further, assume that to change one tire, you perform 18 steps (just go with it). To change all 18 tires, you would perform 324 steps (18 tires x 18 steps each).
Imagine, if you will, the existence of a "magic tire." This magic tire is awesome and works in such a way that when you change one of your 18 tires, your other 17 tires are also changed, automatically, without the need to perform the 306 steps (17 remaining tires x 18 steps each.)
As it relates to changing tires on a semi, of course, no, there is no such thing as a magic tire. However, what if it did exist? Imagine the benefit of the magic tire. Not only would it be really awesome to own a magic tire, when you were at work, you would save so much time.How much time?
Consider the scenario where the 18 steps required to change a tire is equal to 8 hours. Simple math tells me that 18 tires x 8 hours = 144 hours. That's a lot of hours! For the sake of argument, if you could not start changing the next tire until the previous tire was complete and if you could only have one person changing a tire at the same time, I would have someone changing tires continuously 24 x 7, around the clock, meaning someone would change tires on all shifts - 1st, 2nd, and 3rd. Changing 18 tires would require - ready? - 6 days. In realistic terms, if the first tire was started at 12:01 AM on a Monday morning, all 18 tires for a single semi would be done at 12:01 AM Sunday morning. Further, because it's always about money, let's assume that a business owner would need to hire staff to change tires and, for the sake of argument, the hourly rate for a tire changer is $30 per hour.
There's not really anything else, outside of technology, that is similar. For this semi example, you would have to repeat the steps for each tire, but within technology, there is a way to update one thing and to have that update ripple through too many things. I suppose it's similar to when you put a stone in a pool of water. The stone creates ripples in the pond. For me, a blurb of text and a screenshot that is used in multiple places are stones.
Another term for stones in this analogy is "snippet." By definition, a snippet is used to store content that is going to be used in multiple places. Content reuse is thinking about how that snippet can be used in multiple places within your content. Sincerely, I cannot be convinced snippets should be created after all the content is written. I propose that the creation of a snippet must happen during the actual act of writing content. As I write, I need to be conscious of the idea that I want to write the same text I know I wrote elsewhere, I need to create a snippet the second time I determine I need that content.
In addition to my example about the Magic Semi Wheel, this video - What is Content Reuse? is a good example of what we're talking about. Editor's Note: A dinosaur is not a mammal, per https://nayturr.com/is-a-dinosaur-a-reptile-mammal-bird-or-something-else/
Content Reuse is the Topic
This is a good primer for content reuse from Data Conversion Laboratory: Calculating Content Reuse: Where Do I Start?
Another page on the Data Conversion Laboratory site is their page about content reuse: https://www.dataconversionlaboratory.com/content-reuse-learning-center - Content Reuse Learning Center - Your Resource for Maximizing Content Reuse
About this Page
Scattered throughout the other 9400+ posts on this blog are mini-rants about single sourcing in documentation. I have a long-tern goal with this blog, which is to review those existing mini-rants that exist as separate posts and then either move the content within a post to this page or if the rant on that page is integrated too deeply into the existing post, I will simply include a link to that post.
You realize what that sentence just said, right?
There is a rule on this blog.
The rule is this page will be a single source for rants on this subject but if I want to do so, it's okay to keep the existing content in the other place and add a link to it.
It's totally ignoring the foundation of when you apply the concept of having a single source for your content, which is write once and reuse many places.
Yet, I just stated that my rule is to strive for a single place to capture rants about single sourcing, but if I don't want to follow that rule, I don't have to follow it because I allow for exceptions.
Single sourcing content is close to the mythology of the Sith in the Star Wars universe when Anakin Skywalker tells Obi-Wan Kenobi, "You're either with me or against me."
You either apply single sourcing to your content or you don't. There is no fuzziness in the Sith and there is no fuzziness in single sourcing content.
A Reading from the Book of My Career as a Technical Writer
Read, you who are able, the following true story that applies to this idea of "all or nothing." Over a decade ago, I started a new job at a company as a technical writer. First of all, the company had no style guide. Second, the style decisions that were made were determined by the senior technical writer in the department and that was an issue for me. I began editing documents and noticed an inconsistency. It's a sore subject that has been debated since the beginning of the technical writing profession: do you use one space or two after a period. I won't go into the history of using a fixed font versus a proportional font because that's not my point. My point is that I wanted to know when I looked at a sentence with one space after the period, was that correct or if I looked at a sentence with two spaces after the period, was that correct? They both couldn't be correct if the standard was to use one space or if the standard was to use two spaces.
So I asked.
"What is your standard: one or two spaces after a period?"
The answer was "Use one space unless it looks funny; then use two."
Uh, what?
Unless it looks funny is NOT a standard. In fact, it's something an idiot would do, to paraphrase Dwight Schrute.
That is not a standard that can be applied consistently. It would always going to be a judgment call, by the senior technical writer in the department, whether it looked funny.
I should be clear that this squishy standard is not why I no longer work at that company, but it is indicative of an issue I had at that company, which had a manual in which policies and procedures for various tasks were specified; yet, there was not a policy for one or two spaces after a period.
There was no standard because in life, how often do we follow a standard consistently and with no variation? Is it okay to lie to someone? Do you always consistently and without deviation always tell the truth, even when asked if you like someone's new hairstyle? We strive to be consistent, but I fully admit, I fail sometimes. Yet, that consistency is the goal. I want to be consistent, but guess what? Being consistent is hard work. That's why I have an unfortunate truth about the topic of this rant.
Single sourcing is hard work.
Always.
But for it to work, there can be no copy and paste, no multiple versions of the same content, as explained in this 7 minute video: [Quickinar] What is Content Reuse
Otherwise, it's not single sourcing.
Yes.
Every single damn time.
This goes down to the word level:
From Do I need a style guide?:
* Some 15 years ago I was working as a technical writer for a software company. They had several programs that they’d developed and were about to start marketing, but there was NO consistency in how they named one particular program. Let’s call it ‘Jet Forms’ — was it ‘Jet Forms’, ‘JetForms’, ‘Jetforms’, ‘Jet-forms’, ‘Jet-Forms’, ‘jetForms’, or any other variation on this? Between the marketing people and the developers and the website content people, I saw almost every variation you could imagine for just this one product name! I raised the inconsistency in a meeting as I had to document this product and thus use the name hundreds of times, and said we HAD to make a firm decision on what to call it so that EVERYONE used the same term to avoid confusing our customers. We had 8 people in that meeting (2 of whom were the owners of the company), and I couldn’t believe they spent an hour discussing it! It cost the company 8 hours of wages while we haggled over a single word. And no, some 15 years on, I can’t recall what they decided, but I certainly recall the long discussion that was a waste of time and money when just one of the owners should have said, ‘It’s xxx’, and we’d have been done.
As the story illustrates, consistency is the utopia. Otherwise, all you have are cowboys herding cats.
But just for the record, I am not a cowboy.
I am a technical writer.
I am not a word processor.
I'm not a programmer.
I'm not a graphic designer, as the layout of this blog demonstrates <grin>
I know my approach to single sourcing the content with which I am involved can be unpopular. At a different company than the company mentioned above, my approach to writing and maintaining content was viewed as cumbersome by one of my co-workers. The idea of writing content once and reusing it each time is necessary was not done when the content was originally written. My favorite part of the work I did at that company was to analyze a lot of content and try to apply consistency so that there was a single version of a given blurb of text. The hard part was to rewrite the text in such a way as to capture all the nuances of the other versions so I could create a snippet.
What is a snippet? By definition, it's a small piece or brief extract, which is about as helpful as asking, "Why is Metallica awesome?" and replying, "Because they are a heavy band." There's no substance to that definition, which I found through a Google search.
This is not a new idea. I can cite the idea of content reuse going as far back as this article from 2002, which is when Ann Rockley offered her thoughts: Fundamental Concepts of Content Reuse.
In summary and prior to continuing with the words on this page, I want to be clear that reusing content is crucial for working efficiently. Many authoring environments, such as MindTouch include the ability to reuse content as explained on this page https://success.mindtouch.com/Manage/Author/Reuse_content/How_to_reuse_content.
I argue that reusing content is about much more than using a tool to create and maintain content.
I argue that reusing content is about a mindset and about understanding that working efficiently within whatever environment you find yourself is the duty of a technical writer.
I'll admit freely that I didn't always think about content reuse in my day-to-day life during my employment as a technical writer. On Monday, February 10, 2020, I reached a milestone in my career of 25 years as a technical writer. I can say with reasonable certainty that content reuse is a concept I became aware of when I worked at Quintrex Data Systems in Cedar Rapids in the early 2000s. I can recall that there was a check box on, literally, hundreds of screens called Change Print Options in that company's software. As I worked on a project to convert OfficeVision files to Word documents so that I could create WinHelp (.hlp) files, I came to realize manually changing hundreds of Word documents that included that check box Change Print Options would be a waste of time. I understood that there was a streamlined manner in which I could work. In the early days, I recall manually editing .hpj files in Notepad to include a line within the [FILES] section to a centralized Rich-Text Format (.RTF) file so that editing the content about the Change Print Options check box in that centralized Rich-Text Format (.RTF) file would automatically update all references to the the Change Print Options check box. Before I understood that I could manually edit .hpj files in Notepad to include a line within the [FILES] section to a centralized Rich-Text Format (.RTF) file, I literally had hundreds of definitions of the Change Print Options check box spread through literally hundreds of documents. I was starting to understand the value of reusing content.
In this screenshot, there are 16 options available when you go to the Setup menu. Notice that on the list of options Users is available. When you go to a separate page, there is a screenshot of the Setup menu. In this screenshot, there are 7 menu options. Extrapolate that idea for a moment. If there is a Confluence page for each menu option, there are 16 screenshots floating around the Confluence pages.
Obviously, I think this is a gigantic waste of time. With a snippet, there would be one screenshot used across 16 pages and when an option would be added to the list, updating the snippet.
There's also this page - http://universalusability.com/access_by_design/document_structure/separate.html that states the following:
In a nutshell Content that is encoded without display requirements can be accessed by any software or device. Use HTML documents for content, and CSS for presentation.
You should read 3 posts on this blog from 2016, then come back here...
I have a history of writing / tackling this concept on this blog. There are 3 posts on this blog where I explain a concept called "Object-Oriented Documentation" or OOD. These posts are from 2016. To be fair, I used these posts as the pre-writing for this page. I wanted to include those posts here, but when I tested this and previewed what you, the reader, would see, I realized that this page had already become a scrolling nightmare and adding the content from 3 other posts would not be a good strategy.
Thus, you should read the three posts here and then return to this page.
Are you back?
How a Snippet Can be Used
As I've already mentioned, I love the idea of using snippets. The concept of storing content that is necessary to be present in multiple places in a single place gets me animated whenever the topic comes up in any discussion. I believe that all of these concepts are behind the scenes - I don't want the reader to know what text is or is not a snippet. I think that is achieved if the concept of snippets is applied correctly. Another benefit to snippets is to save time and aggravation when it comes to formatting as well. There are choices that are made when it comes to formatting that snippets actually can remove from the technical writer. By not thinking about how to format the content, the technical writer can focus on the content, not the formatting.
Here's a practical example. You want to include a "Note" in your documentation. How are you going to do that? If you want to be consistent, you will create a snippet to format the word "Note" so that the word "Note" is formatted the exact same way, every single time. Otherwise, using a phrase that Val Swisher used in the video above, you end up with content drift. Here are some examples of content drift when the word "Note" is not formatted consistently:
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic |
 |
| Note is not bold, not italic, but is ALL CAPS |
 |
| Note is bold, not italic, but is ALL CAPS |
 |
| Note is not bold, not italic, but in ALL CAPS, first word begins with a lowercase letter. |
 |
| Note is bold, not italic, but in ALL CAPS |
 |
| Note is not bold, not italic |
Just think about that simple example for a moment. There is no reason to have those differences when you can select a snippet that will easily control the formatting.
And it's not about using a copy of how a note was formatted earlier in the document as a base. That's not right either. I don't want to copy / paste content. Lisa P, from 365 Software says it best when she writes:
To put it in simple terms – Write once. Approve once. Use everywhere. This is the goal and this is what your company needs. Why? Because content costs money to create and maintain, it takes a lot of time to create and maintain, and the quality of the content (especially customer-facing content) has a direct impact on revenue and reputation. ... Content reuse is critical for saving money. (source: Selecting the Best Technology to Support your Content Reuse Strategy, Lisa Pietrangeli
Managing Partner, Executive Director of Operations and Business Development, 36Software)
Lisa's summary is why I embedded two videos from 36 Software below. I've been a technical writer for over 25 years. I was hired at NDP on 2/10/1995. Since that day, I have learned many things about the way I want to work. I spent a dozen years doing a lot of copy+paste between documents and it always felt like there was a better way. Turns out there is. My perspective has really been shaped into thinking like a programmer, thanks in large part to understanding content reuse. Many years ago, I remember reading on the HATT email list that if you copy and paste, you are not single-sourcing content. In his article called Single Source All Your Content, published on April 13, 2016, Thomas Aldous defined single sourcing as
source content should be authored and edited in one universal format that eventually gets published in its various output formats like HTML5, PDF, ePub, Mobile Applications, etc. You should never edit the published content directly. If a change is required to the published content, the source should be updated and republished.
I like to apply that concept to understanding how programmers might create modules of code, which is then used in multiple places.
Before I continue, bear in mind, I am writing I want to work like a programmer without knowing what it feels like to work as a programmer.
Therefore, with that in mind, the way I envision this concept in my mind is that if there is a Print button on Screen A and the task is to add a Print button on Screen B, a good / decent / knowledgeable programmer would not copy and paste the code between the area of the code for Screen A into the area of code for Screen B to get that Print button added. Instead, what they would do is separate the part of the code that adds the Print button to a separate module. Then, they would change the area of code for Screen A to reference that module and, also, add a reference to that module to add the Print button to Screen B. I am talking about the part of the code that actually creates the button on the screen and upon being clicked, does the "print" functionality. The point is that you maintain that functionality in a single place. I've discussed this example with programmers and they have reinforced that I 'get' the concept.
What gets me on my pedestal is when I see documentation that begs for content reuse.
And look at step 5. Article 3887 says to "Select AIMSweb manager from the menu." while 3888 says "Select Principal from the dropdown." My guess, without seeing the user interface is that 3887 would have been correct to say "Select AIMSweb Manager from the dropdown." Why use different words to mean the same thing?!?
Webinar about Content Reuse
On Tuesday, May 26, 2020, I listened to a webinar about content reuse. Val Swisher loves content reuse as much as I do! The screenshots I took during the webinar follow the embedded video below:Screenshots
Another Example of Why Content Reuse is Crucial from My Personal Life
I installed Carbonite and selected the y: external hard drive (EHD) to be backed up. Then I selected a second EHD to be backed up and got an error message. I went to the Carbonite documentation to research whether I can specify more than one EHD. I found that no, I can only back up a single EHD.This information was in two different Support articles. By comparing and contrasting the content, it struck a sensitive subject: two versions of the same content.
- On this page - https://support.carbonite.com/articles/Personal-Windows-External-Network-and-USB-Drives - the content is written like this:
- On this page - https://support.carbonite.com/articles/Personal-Windows-Backing-Up-Files-on-External-Hard-Drives - the content is written like this:
If you try to add files from a second external hard drive to your backup, you will receive a message indicating that files or folders backed up from the previous external hard drive will be removed from your backup within 30 days.
but in the second text, it says this:
With your subscription, you are only able to back up a single external hard drive to be included in your backup. If you try to back up a second external hard drive, you will receive an error message. After selecting a second external hard drive for backup, you will receive a message indicating that all the information on the previous hard drive will be removed from your backup. To proceed, click Yes and that external hard drive will be selected for back up.
and shows a screenshot of the message.
There is a way to write the content that is applicable to both articles. I do this on a daily basis. I would write the content once, store it as a "snippet" and then add a reference to that snippet within the page.
Where Snippets fit into a Workflow
Expanding the Idea of Tools, But Just a Little Bit
Tool News
As of Monday, May 1, 2023, I continue to use RoboHelp 2015 for both the Disaster Recovery documentation as well as Knowledge Articles. The Knowledge Article workflow relies upon SMEs to write Knowledge Articles in Cherwell. How long will Cherwell be our ITSM tool? Hmm...
As of Monday, December 5, 2022, I continue to use RoboHelp for both the Disaster Recovery documentation as well as Knowledge Articles. The Knowledge Article workflow relies upon SMEs to write Knowledge Articles in Cherwell. I created this specific paragraph by copying the previous paragraph. Notice a difference? Here it is: the first paragraph specifically cites that I use RoboHelp 2015 whereas this paragraph specifically cites that I use RoboHelp. This is true. On Thursday, December 1, 2022, I submitted an incident to the Help Desk to have RoboHelp 2020 uninstalled on my laptop and to then have RoboHelp 2022 installed on my laptop.
Sometimes, I receive marketing emails from other Knowledge Base software companies. For example, today, I received an email from Document 360, which led me to this 22 video playlist:
How are Snippets Helpful?
Here's another definition of how snippets are useful. In the article Case Study | Hewlett Packard Enterprise....The information engineering team also makes extensive use of snippets, variables, and conditional tags in MadCap Flare to maximize content reuse for its different outputs. ... "Flare variables and snippets are huge time-saving features for us. If we need to change product names for future versions or releases, we can automate those updates by just changing the variables," Fine explained. “With snippets, we remove the need to retype content, helping us to reduce user error and simplify our process of creating content.”
Does it matter that I use RoboHelp instead of Flare? No. This is about the 'concept' of content reuse, not the tool.
I really think it's awesome when technical writers confront the idea that content should be written once and used multiple places. As I outlined above in the Carbonite example, it's essential to be consistent. I remember talking to Lisa Pietrangeli at WritersUA in Memphis, TN, in 2012, about how the product she was demoing accomplished single sourcing with MS Word documents. In her article on LinkedIn, she points out exactly what I believe:
|
Before we continue, let’s all get on the same page about what content reuse means. To put it in simple terms – Write once. Approve once. Use everywhere. This is the goal and this is what your company needs. Why? Because content costs money to create and maintain, it takes a lot of time to create and maintain, and the quality of the content (especially customer-facing content) has a direct impact on revenue and reputation. Whether your company is creating technical documentation, sales proposals, SOWs, or quality standards, content is critical to making money. Content reuse is critical for saving money.
|
That is from https://www.linkedin.com/pulse/selecting-best-technology-support-your-content-reuse-part-lisa. There are three parts to her article and in the second part, I noticed this:
|
When choosing a content reuse solution, you'll need to nderstand your budget and desired implementation timelines.
|
https://www.linkedin.com/pulse/selecting-best-technology-support-your-content-reuse-part-lisa-1 |
Fear not, I emailed Lisa to fix the tpyo! <grin>
|
Then, in part 3, these are the capabilities that any tool being used for content reuse need to have:
|
- Capability #1: Component Reuse
- Capability #2: Metadata and Taxonomy
- Capability #3: Where Used
- Capability #4: Document Assembly
From https://www.linkedin.com/pulse/selecting-best-technology-support-your-content-reuse-part-lisa-2 I think those capabilities are spot-on!
When I see things like this, I shudder. The portion of the screenshot below with the red box was pasted onto the base image to illustrate a point. On one screen in this application, the Delete button is blue while on another, the Delete button is red. Add in the fact that both screens have a Reset button with the same color and size. Why is this? Is it a judgment call? Is it because the software developer thought, "Oh, deleting the whatever on this screen is important and dangerous so I'll make it red?"
Why Snippets Suck
Storing text in a snippet and referencing that snippet throughout an output - a website, a PDF, an eBook, whatever - does not prevent typos and does not save time as far as the time it takes to properly proofread writing. I likely should have made this statement earlier on this page, but here it is now, in a section called Why Snippets Suck. My hope is that this section will become a virtual container for storing the case against using snippets within documentation.Page Length and Snippets
This is from my Write the Docs Newsletter - April 2019 that arrived in my email on Wednesday, April 3, 2019.This month, the WTD community discussed whether users prefer shorter or longer pages in documentation. Both options have upsides and downsides, but most documentarians seemed to feel that longer pages work better for users, and some reported their user feedback has been strongly in favor of longer pages. Here are some of the issues folks discussed:
- It’s important to keep navigability at the front of your mind when you’re writing longer pages. Site search, floating menus with links to sub-topics, and clear sub-headings all help make content more discoverable and skimmable. Plus, if all else fails, users can search for key terms using Cmd/Ctrl+F.
- With shorter pages, users may have to click around through more topics to find the information they need. It’s also more time-consuming for users to use Cmd/Ctrl+F repeatedly on shorter pages.
- On longer pages, it’s easier for users to miss or skip over information they need to know before they get to what they want to know. One person is experimenting with adding validation checks in procedures to help minimize this problem. Most agreed that “we tried to warn you…” is not an ideal solution!
- Because so many topics are listed on a single page, longer pages can make it more difficult to figure out which topics users are reading the most.
What I want to tie the above text to is the idea that snippets have a role in adding to the length of a page. What I mean by this is that if a snippet exists that uses 100 words to explain how a system is used by a company and that snippet is then included on every page that is relevant to that system, the net result is adding 100 words to every relevant page which, in turn, adds to the length of the page. My take on this is that it can be an unintended consequence of using snippets.
Yes, Copying and Pasting is Dumb
Storing text that is used more than once within a snippet is a better strategy than copying and pasting the same text multiple times in multiple places.Storing text within a snippet means that when there needs to be an update to the text, updating the snippet will simultaneously also update all the references to that snippet. My argument is based upon the premise that a snippet will save time and not make any author look like an idiot. However, using snippets does not make the author have a 0% chance of appearing to be an idiot. Certainly, there are times when using a snippet is not a good thing. When a snippet is wrong and then is referenced many times throughout the output, that would not be good. What if the text "Source Reveals Rosenstein Expected To Lave DOJ Very Soon" was stored in a snippet? If the snippet has a typo, the reader sees the same typo (lave should be leave) more than once. And that's bad. And the author looks like an idiot.
As I said, I hope to make this section be where the case for the opposite of my passionate plea to use snippets can be argued.
Is SS Dead?
Is this page worth existing? Mark Baker, who wrote an excellent book I think I read when I worked at Pearson called Every Page is Page One, recently posted Is Single Sourcing Dead? I really hope it isn't because I have some really big plans to use it for our Knowledge Management process at work, especially in light of what I learned last week. I'm making a mental note to return to the Healthcare ID / Hawk ID information ASAP, but I can't write about it now.Some SS Literature
To read some great words about this subject, read Chapter 2 of the below book. The fastest way to get there is to search for "What is content reuse" within the embedded book below.900 Screenshots
Another reason to pursue single sourcing and snippets and content reuse is so that I don't find myself in the same situation as John Dumbrille, who wrote, "Our software's user interface is being updated, all at once, later this year. Our documentation includes 900 screenshots. Advice?"Of course I had advice and some of it was actually meaningful. I wrote the following:
I have gone through this before. I would treat the "revised" system as a "new" system as you are going to have to go through all the tasks in your user guide to catch other changes, such as navigation and enhanced functionality. As you do that work, capture your new screenshots.
One other point. Does this system really have 900 unique screens? If so, WOW! If the 900 screenshots is because you have the same screenshot within multiple tasks, one strategy I would use would be to create a snippet to store that screenshot and then include a reference to that snippet. Most HATs have the functionality (RoboHelp, Flare, Confluence are the 3 I'm familiar with personally). If the same screenshot is currently in 10 different tasks, you would only need to update the snippet.
Sounds like a great project!
It sincerely sounds like awesomeness! I had this type of work with the rewrites of a trouble reporting system. There was Trouble I, then Trouble II, then Trouble II with RELTEC, then Trouble III, then, shortly before I left the company, there was Trouble Management. I never had 900 screenshots in my documentation for that system or any other system, except maybe the service orders system I documented. If I would have known then what I know now, the documentation for that service order system would never have looked the way it did. I was using RoboHelp, but didn't know to use snippets for screen captures - I had to work at Pearson to learn about snippets. Now, that said, for that specific service order system, there were not a lot of duplicate screenshots. Going by memory, I'd guess 95% of the screenshots in that documentation were unique screenshots and not used in more than one area.
Sometimes, it appears the technical writer does understand the concepts I mentioned above. When that happens, the result is really good documentation. For example, I came upon this page: https://smashdocs.zendesk.com/hc/en-us/sections/115000348812-Create-Import-Documents, which is about SMASHDOCs. There are three FAQs, each with their own answer, on three different pages. Pay attention to the wording of the three FAQ answers:
Know what's awesome? Consistency. Each of the questions is answered with the identical statement:
"No, this is not possible. Currently, you can only import Word documents in .docx format in SMASHDOCs."
Assuming the FAQs were written in the order above, the writer didn't take the text in the first question and rewrite the above sentence into a different sentence. They didn't write, for example:
"Unfortunately, not at this time as you can only import .docx format (Word documents) in SMASHDOCs."
And they didn't take that second sentence and write this in the third FAQ, for example:
"At this moment in time, in SMASHDOCs, currently only importing .docx (Word) documents is supported."
I don't see any of those rewrites in their FAQ which means they were consistent. Sure, they may have copied and pasted the sentence from the first to the second to the third, instead of using a snippet and referring to that snippet to achieve the consistency I desire. I'll likely never know...
I remember thinking about using SmartDocs back in 2012 for the user guides at a previous employer. I attended a demo of the product at the 2012 WritersUA conference in Memphis, TN, and remember thinking how awesome it would be to incorporate into the user guides I was working with on a daily basis. The rest of the story is that we shifted to Confluence, instead of a Word-based workflow. Yet, what I thought at the time is true now: snippets and reusable content is the way to go. These two short videos reminded me of that:
This is another example of where snippets and single sourcing documentation makes perfect sense. The red boxes in the screen captures below are around unique text; the purple boxes in the screen captures below are around text that is duplicated in the two articles:
RoboHelp could support having a single topic with all of the content above and then tagging the text in the red boxes as being unique to the specific instance where it is relevant.
I attended a Webinar about a new version of Naavia on Wednesday, November 14, 2018. The new version will be offering additional options for the output that is generated from Naavia. However, my brain is wired uniquely. When I saw that you can rename the name of a section, my brain jumped to the issue that renaming a section would leave references to the pre-renamed name of the section.
As I wrote in the red text on the screenshot here ========>
it's all fine and dandy to rename a section. However, when that is done, you have to edit the text to reflect that new name.
Discover Card Example
I realized this when I was paying my Discover card bill. I found two issues with the website. First, there was a case where there likely was a global find and replace action performed and, because of that, there was a glitch (to me) in how the Discover site works.Before I continue, though, I want to be crystal clear about what would be an easy conclusion.
I don't need, want, or plan to do any sort of "balance transfer" with any of my accounts - I was poking around the Discover.com website and wanted to see how the help text worked for the website.
Now then, this is what happened.
I went to the Frequently Asked Questions section and selected Balance Transfer. It took me to the list of links you see below. I clicked the first link and started reading What is a balance transfer?, expecting to read a definition. I immediately noticed that the second & third words were a hyperlink so I clicked it. I ended up on a different page, marked A. This told me that I could do a balance transfer and how doing so would ...get [me] a low promo rate to help pay them off, which is good information, but it doesn't tell me What is a balance transfer?, as the link had promised to tell me. Then I noticed the tab to the right of the Available Offers tab - called About Balance Transfers - which looked interesting so I clicked it. I ended up on a different page, marked B. This page defined the phrase balance transfer very nicely in two clear sections - What's a balance transfer and Why do one? - where I read the definition of a balance transfer.
Of course, that's when I realized that the text on the initial page did include a definition of balance transfer and when I looked closer at the B page, I noticed that the definitions were not the same. The same text was not used in both places!
Initial Page
Page A
So, which definition is right - the definition on the initial page or the definition on the About Balance Transfers page?
Page B
Here's what I would have done differently. First, I wouldn't have made the second and third words on page A be a hyperlink. I would have added a "To learn more, see [hyperlink]About Balance Transfers[/h]. Second, I would have reworked the text so that the definition of Balance Transfer was consistent between the two pages and, to do that, I would have a snippet with a single definition of the term. Now that I think that through, if the definition on page A and on page B were identical, I would not have a link from page A to page B as there would be no need to make the user click to go to page B to read the identical text. Instead, there would only be a link for Initiate a Balance Transfer on the initial page.
It would be helpful to the user to see the
SAME
Definition
for the phrase so that there is
NO
uncertainty in their mind.
On top of that, I don't plan to take the time to search their entire website and look for any other places that uses the phrase balance transfer - there could be many other places where the phrase is used - there could be no other place where the phrase is used.
I don't know.
I'm not curious enough about their website to look any further into it than what I did.
Besides, I have my own pot boiling with ideas that I need to watch over!
Wouldn't it be neat to have a process that would create snippets of duplicated text automatically and to then replace the duplicated text, within the HTML file, with a reference to the snippet?!? I think so! I hope to nail down what that process involves for my Knowledge Articles. The process must be repeatable and have as little manual intervention as possible. It's a tall order, but I'm a tall guy so I think it will work itself out!!
I decided to remove a link from the list below so that information about this topic is on this page and not elsewhere.
Mary Paez You can create a Knowledge Collection article that lists various (related issues) and have links to the short articles depending on the path taken in the KC article.
Alexander Tsmokalyuk I can, but those are Evolve Loop articles while my goal is to make Solve loop articles as useful as possible. Solve loop articles describe one exact issue.
Paul Hanson Mary Paez, if you have that list of articles and you have it listed in multiple KAs and one (or more) of the articles changes its title, how do you keep that list of articles updated to reflect that title change? Also, how do you track which articles have that list of articles so that you can verify all of the articles with the list are updated?
This is the total essence of what I have been trying to solve with KM and Cherwell (and hopefully RoboHelp) so that things like a list of relevant articles could be set up as a snippet and added to the articles that are related to each other.
What I fully expect to be the answer is to manually maintain that list of articles and to manually track which articles have that list of articles. There's unlikely going to be any sort of automated solution within Cherwell... which is why I want to use RoboHelp! My co-worker and I have made progress with Knowledge Management. When we met with [the project's sponsor] today, we looked at how Knowledge Management will look to the customer, which is something that she had asked us to show her. Thus, we showed her two options:
- store knowledge within Cherwell - translation: a non-RoboHelp solution
- store knowledge outside Cherwell - translation: a RoboHelp solution
The first one is decent, but that second one?!? Holy buckets! It took several minutes to figure out what it was trying to tell me and even after those minutes, I'm not entirely sure I understand its intended message!
I was looking at several of the various Cherwell mApp Exchange options for Knowledge Management on the Cherwell site. I looked at this page - KBI KnowledgeBase - and noticed this:
Stats for a "Good" Number of Views in a Knowledge Repository
|
This was one of the responses:
|
|
I think these are good to keep in mind.
Reason for the Opinion
When I get all excited about writing once and reusing many times, it is because of things like this:
Why 207 list templates - is each unique?
Why 588 Inline Shapes - is each unique?
I can't believe the answers to those simple questions are all "yes, they are unique." Thus, the enemy rears its ugly head: Duplication!!
Extra and redundant work.
Taking more time to do tasks inefficiently.
Waste.
I argue against copying / pasting text, graphics - ANYTHING - within a single document.
If it has to be copied / pasted, it should be referenced. I've often considered what I work on, when writing documentation, to be a type of programming. Would anyone that knows anything about programming believe that a programmer that copies and pastes their code in multiple places is working efficiently? I would answer no.
For more information about "Re-use vs repurposing" in technical writing, see https://www.single-sourcing.com/events/dita-not-dita.
Tested a Theory
 |
The way I see it, it's not the best choice to accept what others tell you.
You should always validate information given to you.
If I had accepted what that team had said, I would be accepting an inaccurate analysis.
What makes me smirk is that the team responsible for the content doesn't know.
The Case Against Manual Numbering
It's a known fact that technical writing sometimes requires numbered procedures when communicating instructions to the reader where each step must be completed in a specific order. For example, step 1 is to open MS Word, step 2 is to write content, step 3 is to format the content, and step 4 is to save the MS Word file. If I were writing that task as instructions, I might write this:- Open MS Word.
- Write content.
- Format the content
- Save the MS Word file.
Additional Information
Editor's Note: The following links might be incorporated into this post in the future, if appropriate.- https://prhmusic.blogspot.com/search/label/Awesome%20jobs%20that%20I%20won%27t%20apply%20for
- https://prhmusic.blogspot.com/search/label/Work
- Still Here Forever and Ever - https://prhmusic.blogspot.com/2019/04/still-here-forever-and-ever.htmlIntroducing Geek Dad - http://prhmusic.blogspot.com/2017/01/introducing-geek-dad.html
- Automatically Generated Garbage - http://prhmusic.blogspot.com/2015/09/automatically-generated-garbage.html
- There's Not a Lot to Say - http://prhmusic.blogspot.com/2013/01/theres-not-lot-to-say.html
- Lars - http://prhmusic.blogspot.com/2017/10/lars.html
- https://prhmusic.blogspot.com/search/label/OOD%20%28Object-Oriented%20Documentation%29
1 comment:
I wrote a set of macros that I thought fiction editors might find useful. One of them is CatchPhrase, which searches your novel for over-used phrases and counts how many times each phrase occurs. Is that the sort of thing you want? If so, it’s one of the 600+ macros in my free book: http://www.archivepub.co.uk/TheBook
Post a Comment