Search This Blog

Single Sourcing Rant

This page began as a post and was then moved to this page. Scattered throughout the other 4000+ posts on this blog are mini-rants about single sourcing in documentation. The long-term goal is to review those mini-rants and either move that content to this page or if the rant is integrated too deeply into the existing post, include a link to that post.

You realize what that sentence just said, right?

Let me restate it:

There is a new rule on this blog. The new 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 the basis of single sourcing content - you want to write once and reuse many places.

And yet, I just created a rule that strives for a single place to capture rants about single sourcing that allows an exception. 

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.

Otherwise, it's not single sourcing.

Yes.

Every single damn time.

I am a technical writer.

I am not a word processor.

I'm not a programmer.

I know that approach to content can be unpopular, especially if it is not done from the very beginning. I've been through cumbersome analysis of content, trying to figure out what text is going to be appropriate for a snippet. My mindset is to, therefore, think about snippets and content reuse during the actual act of writing content. That means as I'm writing, the second time I want to write the same text I know I wrote elsewhere, I create a snippet.

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 a long time. 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 an article 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.

in his article called Single Source All Your Content.

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. 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.
I read this information in two different Support articles. By comparing and contrasting the content, it struck a sensitive subject: two versions of the same content.
Notice how in the first text, it says 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.

Here's another definition of how snippets are useful. From 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:
|
  1. Capability #1: Component Reuse
  2. Capability #2: Metadata and Taxonomy
  3. Capability #3: Where Used
  4. 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?"


My point is there is no reason I can fathom where what that system did is correct in the realm of content reuse. It is the same trap I mentioned at the top of this page - where a standard has been declared but there will be exceptions made, which means it's not a rule.

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 Pearson. 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:



One of the tools I have available to me at work is called Naavia. The neat trick about Naavia is that I can make changes in the text and then spit out a document that has that text in both a flowchart as well as the explanatory text for each part of the flowchart. The advantage of Naavia is that instead of making the text changes both in the flowchart proper and the place where I store the text, I make the text change once, in the place where I store the text and that change is then reflected in the flowchart. If I didn't have Naavia, I'd have a Word document and a Visio flowchart and I'd be trying to keep the text updated. Naavia allows one update to affect two different outputs. Of course, since I am working on Knowledge Management and working within Naavia daily, I see the value. It is a lot like this example, which is from a thread in a LinkedIn Madcap Flare discussion group:



Editor's Note: The following links are to posts on this blog with the tag "Single Sourcing":
  1. 900 Screenshots - http://prhmusic.blogspot.com/2017/02/900-screenshots.html
  2. Introducing Geek Dad - http://prhmusic.blogspot.com/2017/01/introducing-geek-dad.html
  3. Automatically Generated Garbage - http://prhmusic.blogspot.com/2015/09/automatically-generated-garbage.html
  4. Reason for the Opinion - http://prhmusic.blogspot.com/2015/03/reason-for-opinion.html
  5. There's Not a Lot to Say - http://prhmusic.blogspot.com/2013/01/theres-not-lot-to-say.html
  6. Lars - http://prhmusic.blogspot.com/2017/10/lars.html

No comments:

He Got Took

Man's Data Recovery Dilemma Costs Hundreds I really REALLY need to get signed up for BackBlaze to back up all my external hard drives ...