A different perspective on single sourcing

This blog post asks whether or not single sourcing is the best option for creating documents. I’m not sure that I fully agree with everything in the post, but something that the author wrote struck a chord:

I know a single source of content will save me a lot of work. But for other people in the company it won’t. It will mean more work for them, not to mention a very steep learning curve, an investment in software and a strong training commitment. It will save me lots of time and effort—in the long run—but it’s going to double the work effort of ten other people. Where is the benefit?

Thoughts? Feel free to leave a comment.

Usability: as important as the product

A few posts back, Aaron discussed how “effective usage as a far more important factor for realizing value in a software deployment than features and functionality”. That’s not only the case with software, but with Web services, too.

This short article points out:

Online retailers can win customers by maximising usability rather than lowering prices

The benefits of well-planned usability are obvious. Users are able to get more done quickly and easily with a clean, easy to follow interface. It’s not only on the Web, either. It applies to the desktop, too.

If you want a view of this from the perspective of a technical communicator, then read this post by Gordon McLean. It goes into some detail about the usability process he follows.

DocBook for the masses

As I pointed out in a previous post, an OASIS sub-committee was formed last year to explore using DITA for enterprise business documents. It’s an interesting concept that’s been enthusiastically received. Aaron and I are hoping to talk with a couple of people involved in the sub-committee at DocTrain West this May.

Of course, DITA isn’t the only XML kid on the block that can be used for documents other than manuals and the like. DocBook, too, is very capable. Technology book publisher O’Reilly has used DocBook for a number of its titles, as does (at least according to this page) Sitepoint.

But what are the challenges facing anyone who is interested in bringing DocBook to a wider group of users? Fabrice Talbot of LiveTechDocs discusses just that in this blog post. Talbot points out something that the folks on the DITA for enterprise business documents sub-committee have learned:

An important factor in driving user adoption is the availability of software that implements the standard. It would be interesting to see whether big software companies would jump into the bandwagon… Unless the open-source community comes to the rescue!

Another important aspect for user adoption is regularly overlooked: usability. Too often, software vendors release poor GUIs designed for engineers or technical-minded people. As a result, non “XML techies” face a steep learning curve. The creation of their first XML document is often a daunting and discouraging task.

Weekly links roundup

  • Writing user assistance for mobile devices? Then give this article a look. It contains some great advice on how to design for the mobile Web.
  • It’s hard to admit that you make mistakes, but here are 10 common mistakes that technical communicators make.
  • This blog post offers a great comparison and contrast of DocBook and DITA.
  • Ever wonder about what tools Google uses internally for projects? Even if you haven’t, chances are you’ll find this interesting.
  • This article is a interesting overview of the DITA Open Toolkit (among other things).

A few thoughts on writing with a wiki

A few weeks ago, I decided to try using a wiki to work on a couple of personal writing projects. Normally, I’d use a tool like Google Docs or Writeboard, but this time around I wanted to use something that was under my control. On top of that, I needed better linking capabilities than those that Google Docs or Writeboard provide.

So, I installed DokuWiki on my personal Web site and got to work. Some of what I learned (both by trial and error and from reading WikiPatterns and this excellent resource) can be carried over to a documentation department that wants to use a wiki, or to an enterprise that’s adopting a wiki.

Curious? Then read on.

Continue reading

Picking your battles as a consultant

Yesterday, I received an email from an astute reader of our website indicating that a sample in our portfolio contained unnecessary marketing content in the introduction. He said;

Maybe it should go into some marketing material. You want to list the benefits of a product in its documentation to help explain how to use the product. This sentence seems to be trying to sell the product, which is already done.

The content in question was a single sentence in the introduction of a reference guide. Normally, I would agree in principle that marketing content has little use in a reference guide, API guide, data dictionary, and so on. In this case, however, we included it. Why? Continue reading