by Scott Nesbitt

Publishing a book with DocBook  Clip to Evernote

It’s common currency in some technical communication circles to deride DocBook as being dead. If not dead, then gasping its last. But documents authored with DocBook do turn up in a number of unexpected, and expected, places. Places like the documentation for free and Open Source projects. And even at a commercial publisher or two. Like who? Like O’Reilly Media. O’Reilly, according to the DocBook wiki, has “a pure-DocBook workflow for books (from author manuscript to the printer PDFs)”.

This guide (when prompted, enter guest as the user name and leave the password blank) discusses how to get started writing with DocBook. Admittedly, the guide is aimed at authors working on books for O’Reilly, but you can probably learn something from the sections on using Subversion and working with XXE (a popular XML editor).

If nothing else, this guide is an interesting look at an XML-based writing and publishing workflow.

by Scott Nesbitt

Size doesn’t always matter  Clip to Evernote

Rumor has it that when he was Director of Central Intelligence, Allen Dulles would judge the quality and validity of an analyst’s report not by reading it but by hefting it in one hand. The implication there, obviously, was that the heavier the report the more (figurative) weight it had.

When I started in this business, that idea seemed to apply to documentation too — here’s a good story about that. In fact, I remember one employer chiding me because I wrote something tightly and he was expecting about 40% more. That was despite the fact that I packed as much information in that space as the previous writer would have in a longer manual.

But does a manual need to be (in the words of a former co-worker) a tome? Do you need to document everything? Tom Johnson convincingly argues that you should, but not put every bit of information into a single place.

I agree with Tom here. The days of the monolithic tome — whether in print or online — are dead. We have so many ways of giving users what they want, in the way they want it. All it takes is the imagination and effort required to use them. It’s not easy, I admit, but it can be done.

Of course, there are times when a guide should contain everything. And those are more technical guides, like ones covering complex installation and configuration; operational procedures; troubleshooting; and API/programmer references. Once again, you’re not limited to a thick book that falls with a thud. And, once again, you have ways and means to deliver all of that information in a concise, easy-to-use form.

Thoughts? As always, feel free to leave a comment.

by Scott Nesbitt

Presentation mistakes to avoid  Clip to Evernote

Giving a presentation is tough. Even if you’ve done all the necessary work beforehand (and if you haven’t, what’s the point?), you can still stumble and fall. But what are some of the most common, and deadly presentation mistakes?

Here’s a list of 10. Numbers 2, 3, and 8 in the list are some of the most common that I see.

But how do you avoid making those mistakes? By embracing errors and correcting them. You might need to approach your audience for feedback. Or, give the presentation to a colleague or a friend and let them critique you.

Of course, once you’ve fixed a bunch of mistakes in your presenting, a few more will inevitably crop up. But what’s the point of doing something when you can’t use it as a learning opportunity?

by DMN Communications

Weekly links roundup  Clip to Evernote

by Scott Nesbitt

Using Impress to create a demos and mockups  Clip to Evernote

When creating a demo or a walkthrough, the first piece of software that comes to mind is probably a screencasting tool like Camtasia or Captivate. Good tools, but what if you’re on a budget or if you need to quickly cobble something together or do a mockup?

Well, check out this article. It outlines how to use OpenOffice.org Impress to create software demos. Good advice not just for developers, but for people who create technical marketing material.

I’m sure technical communicators can also use the techniques from the article to create mock-ups of online help systems or even to storyboard screencasts.

by Scott Nesbitt

Lessons learned in planning and managing a documentation project  Clip to Evernote

In June of this year, a project to update the Ubunutu community wiki — dubbed “Summer of Documentation” — was undertaken by a few member of the Ubuntu community. Unfortunately, the project didn’t turn out as expected. Work got done, but not as much as hoped.

Continue reading →