Blog Archives

Bit rot in the documentation

This week I’m attending Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. It’s a privilege to be here, and to speak at this cool get-together.

My session is called Bit Rot in the Docs. (The link goes to the slides on SlideShare.) The presentation looks at how documentation can degenerate over time, and some techniques for finding and fixing errors.

The very mention of bit rot will strike terror into an engineer’s heart. “Unused programs or features will often stop working after sufficient time has passed, even if ‘nothing has changed’.” (From the hacker’s Jargon File.)

Bit rot affects documentation too. Whether the cause be a changing environment, human error, or the infamous cosmic rays, we need to root out that rot. But should the technical writer read and test the documentation on a regular basis? That’s the least efficient and most error-prone way of detecting doc decay.

Instead, in this session we looked at the following techniques:

  • Automated testing of code samples.
  • Documentation reviews as a standard part of engineering team procedure.
  • Collaborative spot-testing.
  • Customer feedback.

For more details of the session, see the slides on SlideShare.

Bit Rot in the Docs

The DITA debate

I’m coming to the conclusion that there are specific types of content that suit a DITA environment, and that the converse is also true: DITA is not the best solution for every content type. (DITA is the Darwin Information Typing Architecture, an XML architecture for designing, writing, managing, and publishing information.)

“Well, duh,” you may say. :) I’ve never worked in a DITA environment, but I’ve attended two indepth training courses and a number of case studies that walked through successful DITA implementations. The most recent was at the ASTC (NSW) conference last week, where Gareth Oakes presented a case study of an automotive content management system that he designed and implemented in collaboration with Repco. The content is stored and managed in DITA format, and published on a website. (See my report on the session: Repco and DITA.) This was a convincing case study of a situation where DITA has succeeded very well.

In my analysis, the DITA implementations that work well are those where the content consists of a large number of topics, and where those topics have an identical structure. It’s almost as if you’re building a database of content. Good examples are catalogues of automotive spare parts, machine repair instructions,​ safety procedures, aircraft manufacturing manuals, and so on.

Apart from volume and support for a standard layout, this type of content has other requirements that DITA can satisfy well, including the ability to automatically build a variety of manuals by combining the topics into different configurations (via DITA maps) and multi-channel publishing.

On the other hand, some content doesn’t benefit much from such a highly structured storage format. Potentially, the overhead of a DITA environment is overkill and the costs may outweigh the benefits. If we have contributors to the docs who are not tech writers or developers, asking them to learn DITA or specific source control and editor rules can be a deterrent.

Dare I say it: Much of the documentation we write in the software industry falls into the latter category. Our topics tend to be lengthy, less uniform in structure, and more discursive than, say, an auto parts manual. API reference docs are an exception, but they’re auto-generated from software code anyway. We also don’t usually need to recombine the topics into different output configurations, such as different models of a car.

What do you think? Please contradict me. :) Do you have examples that gainsay or support the above conclusions? I’d love to see some examples of well-structured and well-presented documentation produced from DITA source.

Out of print: “Confluence, Tech Comm Chocolate”

A few months ago, I asked my publisher to take my Confluence wiki book out of print. The book is titled “Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication”. It takes a while for the going-out-of-print process to ripple across all the sources of the book, but by now it seems to have taken effect in most sellers.

solong_300pxWhy did we decide to take the book out of print? I’m concerned that it no longer gives the best advice on how to use Confluence for technical documentation. The book appeared early in 2012, and applies to Confluence versions 3.5 to 4.1. While much of the content is still applicable, particularly in broad outline, it’s not up to date with the latest Confluence – now at version 5.6 and still moving fast. I thought about producing an updated edition of the book. But because I don’t use Confluence at the moment, I can’t craft creative solutions for using the wiki for technical documentation.

Here are some sources of information, for people who’re looking for advice on using Confluence for technical communication:

  • If you have a specific question, try posting it on Atlassian Answers, a community forum where plenty of knowledgeable folks hang out.
  • Some of the Atlassian Experts specialise in using Confluence for technical documentation. The Experts are partner companies who offer services and consultation on the Atlassian products. The company I’ve worked with most closely on the documentation side, is K15t Software. I heartily recommend them for advice and for the add-ons they produce. For example, Scroll Versions adds sophisticated version control to a wiki-based documentation set.
  • AppFusions is another excellent company that provides Confluence add-ons of interest to technical communicators. For example, if you need to supply internationalised versions of your documentation, take a look at the AppFusions Translations Hub which integrates Confluence with the Lingotek TMS platform.

A big and affectionate thank you to Richard Hamilton at XML Press, the publisher of the book. It’s been a privilege working with him, and a pleasure getting to know him in person.

For more details about the book that was, see the page about my books. If you have any questions, please do add a comment to this post and I’ll answer to the best of my knowledge or point you to another source of information.

Want a REST API to play with?

Are you just starting out with REST APIs, or curious what they look like, and want one that’s easy to play with? Have a go at this tutorial I’ve just written for the Google Maps Engine API: Putting your data on a map.

A few things make it easy to play with the API via the tutorial:

  • You can get started immediately. All you need are a project on the Google APIs Console and a Google Maps Engine account, both of which are freely available. The instructions are in the tutorial.
  • The API accepts requests via an online interface called the Google APIs Explorer. So, instead of having to send HTTP requests and parse responses via the command line or within a program, you can just use an online form. The APIs Explorer prompts you for the fields and parameters that are required for each API request. I’ve integrated the APIs Explorer into the tutorial, so each step of the tutorial offers a link to the appropriate form in the APIs Explorer.
  • If you use the APIs Explorer, you can skip the bit about OAuth and client IDs. Yaayyy for a touch of simplicity when first getting to know an API!
  • The tutorial includes the full HTTP URL and request body for each API request. For those into Java, there are Java code snippets and a downloadable sample app.
  • After performing each step of the tutorial, you get visual confirmation of results. So, you’ll follow instructions to send a request via the API, then you’ll look at your account in Google Maps Engine online to see what’s changed.

More about Google Maps Engine, its web interface, and the API

Google Maps Engine provides a means to store geographic data in the Cloud, and to superimpose that data on top of the Google base map. Geographic data can be vector or raster. In the tutorial, you’ll use vector data consisting of a set of geographic points (latitudes and longitudes) with the associated information that you want to represent on a map (in this case, population growth statistics).

Google Maps Engine offers a web UI (user interface) where you can upload data and customise your map. It also offers an API (application programming interface), so that you can upload and manipulate your data programmatically. This particular API is a REST API, which means that it accepts requests and sends responses via HTTP. The requests and responses use JSON format to represent and transfer data.

When following the steps in the tutorial, you’ll use the API to do something, such as upload a set of vector data, and then you’ll look at the UI to see the results.

What you’ll have achieved by the end of the tutorial

When you’ve finished the tutorial, you’ll have your very own interactive map in Google Maps Engine, looking like the screenshot below. The circles show population growth (blue circles) or decline (red circles) in countries around the world. The size of the circle represents the size of the change:

Screenshot of map

Let me know if you try it

I’d love to know how you get on with the tutorial, and what you think of the API. Here’s the link again: Tutorial 1: Putting your Data on a Map.

How to track textual input with Google Analytics

This week an analytics ninja showed me how to use Google Analytics to track the values entered into a text field. It comes down to sending a dummy page name to Google Analytics, containing the value entered into the field. Google Analytics faithfully records a “page view” for that value, which you can then see in the analytics reports in the same way that you can see any other page view. Magic.

For example, let’s say you have a search box on a documentation page, allowing readers to search a subset of the documentation.  It would be nice to track the most popular search terms entered into that field, as an indication of what most readers are interested in. If people are searching for something that is already documented, you might consider restructuring the documentation to give more prominence to that topic. And how about the terms that people enter into the search box without finding a match? The unmatched terms might indicate a gap in the documentation, or even give a clue to functionality that would be a popular addition to the product itself.

It turns out that you can track input values via Google Analytics. The trick is to make a special call to Google Analytics, triggered when the input field loses focus (onblur).

<input onblur="ga('send', 'pageview', 'my-page-name?myParam=' + this.value);" />

The above ga call sends a customised page view to Google Analytics, passing a made-up page name that you can track separately from the page on which the input field occurs. The made-up page name is a concatenation of a string ('my-page-name?myParam=') plus the value typed into the input field (this.value).

The string my-page-name can contain any value you like. It’s handy to use the title of the page on which the input box occurs, because then you can see all the page views in the same area of Google Analytics.

Similarly, the part that contains the input text can have any structure you like. For example, if the page is called “Overview” and the input field is a search box, the Google Analytics call could look like this:

<input onblur="ga('send', 'pageview', 'overview?searchText=' + this.value);" />

This blog post assumes you have already set up Google Analytics for your site. See the Google Analytics setup guide. The Google Analytics documentation on page tracking describes the syntax of the above “ga” call, part of “analytics.js”.

Follow

Get every new post delivered to your Inbox.

Join 1,499 other followers

%d bloggers like this: