The World Without Documentation

“What a wonderful world this would be”

by SamCooke

Great song. But just consider for a moment what a wonderful world it would be without documentation…

Who Needs Documentation?

Agile software developers adhere to their manifesto of minimal documentation. Ideally, this means no documentation. Obviously this is intended to produce a product where the user knows immediately how to use it without having to read anything. How intuitive.

Teachers are the first to say that people learn different ways. Not everybody reads. True, many people consider themselves visual learners. But isn’t it a “wow” moment when you hear somebody say, “I can’t think of the last time I read a book.” Even if you are a visual learner, is it a justifiable reason to throw all documentation into the trash and stop producing documentation?

For a second, consider some of the issues the world would face if documentation goes away:

  1. No laws written down. Anarchy
  2. No written music. OK, only the musicians with a great memory can play.
  3. No ownership. How can you prove property ownership with a he said-she said?
  4. No Standard Operating Procedures (SOPs). Consider the verbal training that would have to occur and the slow-down of business
    before everybody on the assembly line knows what is going on and expected.
  5. No written contracts. How do you know what work is going to be done and what you agreed to? Back to the handshake is a man’s word.

So, what does this mean as digital technology runs pell-mell over documents as we know them, and all communication and transactions going to mobile devices?

Well, the advantages of course are the mobility and flexibility – a better user experience (TBD)? But where are the checks and balances?

It’s bad enough that people don’t know how to read their receipts from the store, or their EOBs from their insurance companies. But where will the paper trail be for tracking purchases against bank accounts? Taxes will be a nightmare (more than they are already)!

Are we to take for granted that the appropriate controls are in place to ensure we aren’t getting ripped off on a daily basis? What about the proof of what was purchased, or being able to compare the quality of the goods promised against what you received?

“Sir, do you have your receipt?”

Documentation, whether in paper form or digital, will still have to include controls as well as secure processes to ensure appropriate storage, retrieval, and archiving. Otherwise, how will we ever remember what we did last year, let alone what the previous generation did?

Please add your comments.

Posted in documentation | Tagged , | 1 Comment

It’s Time to Clean Up Your Documentation

Companies invest a lot of money into developing and delivering content. Shouldn’t it perform for you?

Don’t you hate going through a SharePoint server or wiki trying to find the latest information about some company product or service? Usually, what you find are duplicate and outdated articles, in multiple departmental silos of data. After a few attempts, you give up and start surfing the Internet for answers. (And you wonder why You Tube videos are so popular.)

How Do You Value Documentation?

If you value documentation – yes, actually put a dollar-figure on it – you would think twice about  leaving content sitting on a shelf gathering dust because (for some reason) nobody is using it.

The corporate sage who measures ROI on every asset in the place should apply the same precision assessment on documentation (yes, each piece of content). In other words, content is no different than other “assets”. It has some value. But without monitoring and measuring it, you don’t know what it is. 

The Best Practice to avoid document “shelf decay” is to revisit your content on a periodic basis. That way you won’t end up buried in old, stale, nobody-uses content. (Clutter is a real turnoff to anybody searching for information they need NOW!)

Time to Get Out the Shovel

Once a month or quarter, ask your technical writers to cull through the content on your web site(s) and intranet. They should:

  • Assess the validity. Has the related product/service changed? If so, the content needs to be updated.
  • Check the feedback.  Is there anything from customers, partners, and employees? Respond to questions and complaints.  
  • Look at the number of visitors. Ask yourself why some are performing better than others. The content objects that show no activity should be removed – yes, archive it. Or maybe the asset needs to be refreshed. Give it some life – add graphics, videos, animation, quotes from experts, or something else to generate visits and comments. 
  • Promote content that supports your products and services. If you aren’t doing this, how do you expect anybody to find what you sell? If you make it hard to locate the information, your people will simply go somewhere else where it’s easier to get their answers.
  • Apply new branding guidelines. If Marketing has introduced new branding guidelines, your site pages and attachments should be revised so they appear current (in other words, all content should be aligned with the Marketing program).

Customers, Partners, and Employees Want to Be Informed

Your goals should be to provide the latest information to your visitors, as well as manage the clutter to a minimum. Think of it as keeping your assets in shape.

If you are not doing this, you are not taking advantage of your technical writer resources. Technical writers are not only good at creating new content but also repurposing existing content for better performance. And, technical writers are getting savvier about SEO techniques and metrics.

Improve Your Content ROI

It takes assessment, strategy, and a bunch of work to make your content perform. But if you don’t do it, who will? There is nothing worse than a lot of effort put into creating documentation that nobody reads or uses.

Why have assets unless they are going to provide a return? Treat your content like you do your financial investments. If it’s not performing, change what you are doing.

Give me a shout, and tell me what is working for you in promoting your content and garnering user feedback.

Posted in documentation | Tagged | Leave a comment

Simplify Critical Information with QRGs

Team of IT specialists in datacenter working by network servers

At some point somebody will ask you if you have a Quick Reference Guide, or QRG. These documents are useful for summarizing operational information about products, services, and processes for employees, partners, and/or customers. They are for “quick reference” and easy to use because they summarize the critical operational information.  If you don’t have one, you may be a bit perplexed how to create it. However, it can be fairly easy to do.

A QRG is similar to a data sheet but more like a spec sheet. Instead of trying to influence the reader to buy something, you are striving to help the reader quickly find the most commonly required information for daily operations. If you can focus on the key components of the topic that need to be shared with users, and have a template for the structure, it is simple to assemble. As with data sheets, writers attempt to keep QRGs to a maximum of two pages when possible.

Recently I was asked by a colleague if I had a Quick Reference Guide that I had created a while back for a project we both worked on. Of course I still had a template and a few drafts. So, I thought I’d share them with you (names changed of course).

It may be easier to design the template you will use before you worry about filling it in with real data. Typically, I consider the structure (e.g., types of components) first and then the layout. Once you have your template set up, you can use it for each QRG, and modify it according to the corresponding subject matter.

Structure and Layout
Typically, the QRG will contain an overview, some graphics and tables, and links to related content, such as useful tools, contacts, and reference material. This is the information that you want to be literally at the fingertips of the reader. It is a “quick reference” for people on the job, such as field personnel and customer support. That’s why it has to be brief and to the point. The information must be easy to find.

For the layout, you should have access to the branding guidelines from your Marketing department. The layout may need to include marketing/legal requirements, such as copyright notice, logo and trademarks.

The following is a very basic sample template without any text or data. As you can see, it shows the main sections, and encourages use of tables and graphics wherever possible to organize the content.

Key Components of the Product/Service/Process
Think about what somebody in the field needs right at his/her fingertips. Not only is this information useful for on-the-job projects, but excellent for training purposes. You have to reduce the subject matter down to just the basics, the most critical or commonly used data the reader will need.

Once you have a list of what you would like to include in the QRG, it’s time to figure out how you can fit it all into the available space – again, typically two pages. Sometimes you can reduce the data footprint by including it in a table or a graphic (e.g., an infographic). Of course, you don’t want the content so jam-packed that it is not readable. If some of the material won’t fit, maybe you can summarize the critical information and include a link to a another document for additional information.

The following draft illustrates information as it has been inserted in the template, organized in bulleted lists, tables and graphics. There is still a lot of real estate available on the two pages to add more useful content to aid the reader.

 Sample QRG

Have fun creating your own QRGs!

Posted in documentation | Tagged , | Leave a comment

Developers are Wizards – With Writers, Developers are Experts

, ,      . . , , .       ,  .    , .To document is often considered unnecessary for one’s time. Let’s face it, developers think “code”. Documenting code is an extraneous after thought, tucked in at the end to meet customer acceptance criteria. This is conveniently referred to in management parlance as “just in time.” 
If we were back in the Middle Ages, a developer would be considered a wizard. Somebody doing strange, magical things. Somebody to be feared, and maybe burned at the stake. But a scribe could translate that wizardry for the masses. The developer would be revered as a craftsman, an expert in one of the guilds, pursuing the king’s business, rather than something mysterious and evil.

Of course, most people couldn’t read or write back then. But by combining scribes with publishing (thanks to Gutenberg) the masses became educated people of the Renaissance with an enhanced view of the benefits of the developer’s code.

Today, developers are experts, SMEs. They continue to be so thanks to the support of writers who translate how to use and benefit from those sometimes mysteriously cryptic offerings left by those guilded developers.

Posted in documentation | Tagged | Leave a comment

10 Things You Should Have Before Starting a New Contract Techwriting Project

Before starting a new project as a contract technical writer, be prepared for success. Here are 10 things you (and your customer) can benefit from having up front:

  1. Signed contractor agreement – This is absolutely necessary to ensure you get paid and the rules for both sides are clearly stated.
  2. Project purpose and objectives – What are the objectives? You need to know the end goal.
  3. Target audience – Who will you be writing for? Experienced IT administrators, employees, or customers?
  4. Content type – Is it a guide (with how-to procedures), a datasheet (overview) or whitepaper (use case and concepts)?
  5. Owner of this document – Who do you have to please?
  6. Subject matter experts and other resources – Know the SMEs you can contact and the other resources you can use (related documents, access to product for research, etc.)
  7. Format and outline – Is there a template or marketing guidelines you need to follow? What is the basic structure for the project?
  8. Project workflow – Agree on the process and the schedule you need to follow to include draft, reviews, and delivery.
  9. Change management process – Define how changes will be requested and how changes will affect your work, such as price (if fix priced) and schedule (deadine).
  10. Acceptance requirements – Agree on the acceptance criteria: your deliverables and the customer’s sign off.
Posted in documentation | Tagged , | 6 Comments

Managing Templates

Anybody can write. Well, they’ve been lead to believe they can by the manufacturers of word processing software. And to the extent that anybody can create a document with content, this is true. However, publishing the document with the the rudiments of communication decorum, e.g., consistent fonts, layout… basic appearance, not to mention organization is another story. To create “consistency” many organizations look to use templates. The problem is that most users have no clue about basic template building.

Stay tuned as I reveal common errors users make when attempting to create and use templates to create documents.


Posted in documentation | Leave a comment