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.

I've been a technical writer for a long time - 21 years, 10 months, 4 weeks, 1 day or 8003 days. In all of that time, I have learned the way I want to work is to approach my content as programming code. It was not always like this. 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. Over the last 5 years, 7 months, 1 week, 1 day or 2049 days, my perspective has really been shaped into thinking like a programmer. My understanding of programming is that you create modules of code, which are then used in multiple places. A simple example 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.

Why am I writing about this? Because I can't turn off my "work mind" on Sunday, January 8, 2017, at 8:49 AM. I also realized I have ranted about this concept in multiple posts on this blog and find myself repeating myself and (gasp) writing multiple versions of the same content.

Today, what got me on this train in my brain is the Carbonite documentation. I installed it earlier this morning 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. Snippets ROCK!

Single Source All Your Content

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!
Here's another thought. When I think about why content reuse is important to me, as a technical writer, I think about how the programming / software development concepts I have read about over the last 20 years have led me to the idea that "good" software developers reuse widgets and UI elements whenever they can. For example, if Screen A has a Print button and Screen B needs to have a Print button added, the developer would use the same code on both Screen A and Screen B - they wouldn't copy / paste the code from Screen A to Screen B. They would isolate the Print code and make it so that Screen A & Screen B use the same code when the user clicks Print. Granted, I've never been a software developer so I may be incorrect but that's what I've read about over the years.

Thus, 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:



Editor's Note: The following links are to posts on this blog with the tag "Single Sourcing":
900 Screenshots - http://prhmusic.blogspot.com/2017/02/900-screenshots.html
Introducing 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
Reason for the Opinion - http://prhmusic.blogspot.com/2015/03/reason-for-opinion.html
There's Not a Lot to Say - http://prhmusic.blogspot.com/2013/01/theres-not-lot-to-say.html 

No comments:

Selling the Farm

Former METALLICA Bassist JASON NEWSTED Selling Montana Ranch For $5 Million