Choosing an XML schema  Clip to Evernote

Frame versus Word. Robohelp versus Flare. DocBook versus DITA. Coffee versus green tea. Those are some of the debates that many of us in the technical communications field take part in regularly. OK, maybe not the last one …

But I think that the DocBook versus DITA debate is one of the biggest ones going on right now. This article at The Content Wrangler looks at the DocBook and DITA’s strengths and how to make the choice. Teresa Mulvihill (with whom Aaron and I will be doing a podcast interview at DocTrain West) also wrote an excellent comparison of these rival XML schemes.

My take? DocBook and DITA both have their places. They’re both excellent for single sourcing. DocBook is better for what I call monolithic single sourcing, while DITA is better suited for discrete single sourcing. If you don’t have a lot of reuse of content in your organization, then DocBook is a good choice. If, on the other hand, if there is (or you anticipate) a lot of reuse then consider DITA.

Thoughts? Feel free to leave a comment.

Hiring the right technical writer  Clip to Evernote

In many ways, technical communications is just like any other field. When it comes to the people doing the job, the level of skill, dedication, and competence varies from person to person. You have outstanding practitioners and those who are in the job only for a pay packet.

I recently read an article at that looks at the problems you might face when trying to hire a writer. Some of the advice is old hat; some of it useful.

Continue reading

Weekly links roundup  Clip to Evernote

  • Interested in learning how to document an API? This book will give you a good introduction.
  • This article (it’s a PDF) discusses screencasting, and how to apply it to documentation.
  • One session at the recent CMS/DITA conference examined how wikis “could be an easy entry into the world of CMSs, collaborative authoring, and XML -based outputs”. This blog post at Palimpsest is a detailed recap of that session.
  • Writing useful error messages can be tough. Here are a few useful tips.
  • Sarah Maddox discusses how using a wiki helped her team create some documentation on a very tight deadline.

Thinking like a user  Clip to Evernote

Charles Cooper at The Rockley Blog has written an interesting post on the need to think lke a user when developing a document.

Cooper makes one cogent point:

The fact is, most people, especially those who are new to our product (or concept, or service) just don’t have the background they need to ‘instinctively’ find what they’re looking for. So much of what we think of as ‘instinctive’ is really backstopped by prior knowledge.

Continue reading

Dealing with errors and omissions  Clip to Evernote

Regardless of what we’d like to believe, technical communicators aren’t perfect. Neither are the development and project management teams with whom we work. Sometimes we get things wrong and that makes it into the final release of the documentation. Or, for whatever reason, something gets missed.

Nowadays, most documentation is distributed electronically — as a PDF, HTML, a help system, or all of the above. So, it’s a lot easier and cheaper to issue updates to documentation. In a number of shops in which I’ve worked over the last few years, updates and changes and corrections have been slipped in rather stealthily: replace the old electronic version with the new.

The other day, I was browsing the documentation at the Web site of Red Hat. I noticed something interesting while I was there: a link to documentation errata. I haven’t seen something like that for a while, and it’s a nice touch.

The errata page links to updates for various guides. There are also detailed instructions on how to submit corrections using Red Hat’s Bugzilla tracking tool.

How do you deal with errata? Feel free to leave a comment.