I’d Rather Be Writing - Tom Johnson

Presenter: Joe Sokohl (http://sokohl.com)
Conference: Doc Train West 2008

In this presentation, Joe Sokohl talks about gathering user research prior to designing and implementing your help deliverables.

Breaking the Rules

First you have to know the user. You have to talk directly to the person doing the task. It all comes down to understanding who the user is. Talk to real users doing real work in actual contexts. Interview real people doing real activities. “Don’t speculator, Don’t argue. Observe” (Don Norman). Everything starts with user research.

Joe interviewed actual users in their cubicles in their offices, asked them how often they used the product, how often they did various tasks. He also said, “By the way, could you show me the user manual for this software?” Hardly anyone could produce the manual. One lady finally dug it out at the bottom of a cluttered drawer.

Read the rest of this entry »

Download MP3
Duration: 5 min.

In this short podcast, David Holmes talks about how he and his team migrated 50,000 unstructured pages to DITA. Here’s his official presentation title and a brief description:

From Planning to Publishing: How Business Objects Migrated Documentation to DITA One Step at a Time

In 2006, Business Objects faced a major challenge. How to migrate over 50,000 pages of unstructured non-topic based documentation it had acquired through rapid growth and acquisitions. The answer was to use DITA to standardize content creation, management, translation and publishing processes company-wide.

(By the way, David won my free Doc Train ticket contest, but then he was later asked to speak at the conference anyway.)

Note: This podcast was recorded at the Doc Train West 2008 conference in Vancouver, British Columbia.

Guy Kawasaki writes, “A PowerPoint presentation should have ten slides, last no more than twenty minutes, and contain no font smaller than thirty points” (The 10/20/30 Rule of Powerpoint). I wish everyone who prepares a presentation would follow this advice. Long PowerPoints disrupt any kind of narrative flow and dynamic energy that can build up when you deliver your message.

Download MP3 (right-click, select Save As)
Duration: 43 min.

In this podcast, I talk with Alan Porter, vice president of Operations at WebWorks, about the Web 2.0 technologies they’re using to reach out to their customer base. In addition to using blogs, wikis, and social networks to connect with customers, WebWorks also uses wikis to facilitate communication and collaboration within their company.

Alan says they consider themselves a “wiki-driven company” because the wiki drives the way they do business. WebWorks has an internal wiki (which replaced their old intranet), a projects wiki (used to communicate with their customers on project work), an external wiki for their help center (where customers can interact directly with developers and support), and a wiki for organizing their upcoming user conference.

Read the rest of this entry »

One of the things I like about WordPress is its versatility. WordPress isn’t just blogging software. With the right theme, you can build a website that doesn’t resemble a blog at all. Essentially, writers who become familiar with WordPress become empowered as web designers as well.

A few weeks ago, I made a website for a client who was launching a green building business (see or click the image below).

It’s a predesigned theme that I purchased from ithemes.com, customized a bit and configured. I also wrote the content. I like WordPress because you don’t have to start from scratch with the theme design. If you get a system down and are familiar with the theme you’re implementing, you can create a professional site fairly quickly.

However, if you undertake such a project, triple the time you estimate for your first project, because it just works out that way. (Also, as always, the writing of the content is often more difficult than the actual site creation.)

My point is basically that WordPress doesn’t just have to look like a blog. It’s a micro-CMS that also empowers less technical users to control and manage the text on the pages without using Notepad or Dreamweaver.

I wrote a WordPress Quick Start Guide in wiki format and posted it on the WordPress Codex. Check it out here: http://codex.wordpress.org/WordPress_Quick_Start_Guide.

This guide gives you a quick introduction to the most important tasks and concepts in WordPress. It divides these tasks and concepts into five sections, outlined below:

Get Set Up

• 1.1 Advantages of Self-Hosted WordPress Blogs
• 1.2 Become Familiar with FTP
• 1.3 Install WordPress on Your Web Host
• 1.4 Explore Your New WordPress Blog
• 1.5 Configure General Settings
• 1.6 Import Your Content from Blogger or Elsewhere

2 Create Content

• 2.1 Write a Post
• 2.2 Create a Page
• 2.3 Make Categories for Your Posts
• 2.4 Add Tags to Your Posts
• 2.5 Edit a Page or Post

3 Style Your Site

• 3.1 Change Your Theme
• 3.2 Modify Your Sidebar
• 3.3 Customize Your Header Image or Background
• 3.4 Configure How Your Pages Appear
• 3.5 Make It Easy to Subscribe to Your RSS Feed

4 Add More Functionality

• 4.1 Install a Plugin
• 4.2 Activate Akismet to Stop Spam
• 4.3 Create a Regular Database Backup
• 4.4 Include a Contact Form
• 4.5 Install Other Needed Plugins

5 Understand the Code More

• 5.1 Understand A Little Bit About Template Tags (PHP)
• 5.2 Modify Your Theme’s Appearance
• 5.3 Understand Your Theme’s Files
• 5.4 Recognize the Loop
• 5.5 Learn How to Upgrade Your Blog Software
• 5.6 Learn How to Get Help

I wrote the guide because I’ve felt, for some time now, that the WordPress Codex is too massive to be useful for anything more than reference information. There needs to be a shorter, more concise way of getting up to speed with WordPress.

I think my basic organization and content is okay, but the wiki format is challenging. It looks quite long, it’s not too printer friendly (although you can print it), and there aren’t any images (which means it’s not very visually attractive). Writing in wiki format is hard (easy to write, hard to make look professional).

If you have any suggestions for how I might improve the Quick Start Guide, let me know. Actually, if you want to get involved as a WordPress Codex author/editor, see Contributing to WordPress. After you register for an account and log in, and then change the skin to Monobook, you’ll see an Edit button you can click to edit the wiki content. I’d love if it some of you out there actually edited this guide.

I attended an STC chapter meeting tonight, and while the presenter had some excellent information, only 6 people showed up — the presenter, the program manager, a new guy, two regulars, and me. I thought this was okay because we were recording the event anyway, but I’m sorry to report that I botched the recording. The mic jack wasn’t snug in its socket, so you can’t hear anything.

Read the rest of this entry »

I updated the date and time for the WordPress course. Instead of this Saturday, I’ve moved it to next Wednesday evening. Here are the updated details:

Date: Wednesday, April 30
Time: 7:30 p.m. CST
Location: Web
Cost: $99
Course Size: Limited to 15 participants

I hope this can better accommodate all of you who emailed me to say that you have previous engagements this Saturday. If not, I’m sure I’ll do some more training in the future.

For more details about what the training will cover and how to sign up, see WordPress for Beginners Course.

Blaze is a new Framemaker alternative that Madcap Software has just released into beta. With Blaze, you can create printed documentation and publish it to Word, Framemaker, PDF, XPS, and an XHTML book (but not webhelp).

When I first heard of Blaze, my immediate question was — Doesn’t Flare already publish to Word and FrameMaker? If so, why would I need Blaze?

The short answer is, you don’t need Blaze if you already have Flare. But if for some reason you only write printed documentation, and never online help, then Blaze might be for you.

Despite the irrelevance of Blaze for my project needs, Blaze does have a new review feature that is unique and worth exploring. As you know, you often you need SMEs and other team members to review your content. When your content is trapped inside a help authoring tool, you can’t quickly send SMEs a file to review — how could they open it? As a result, we traditionally publish our help to Word or PDF, print it out, and then stick it on the SME’s desk. Read the rest of this entry »

Download MP3 (right-click, select Save As)
Duration: 42 min.

DITA is a topic I’ve wanted to do a podcast on for a long time. When I heard a local technical writer express her enthusiasm about how she was using DITA (Darwin Information Typing Architecture) at her company, I knew I found the right person.

In this podcast, Marlene Martineau of New Dawn Technologies explains why they adopted DITA, how they adopted it, the benefits they’re experiencing, and the reasons why she’ll never go back.

If you’re unfamiliar with DITA, it’s a way of tagging your content so that the DITA Open Toolkit can transform it into a number of outputs, such as HTML and PDF. The tags conform to a specific XML architecture, and your information is chunked into small topics that can be arranged in different tables of contents (”maps”).

DITA is quickly becoming the XML standard for technical writers. New XML editing tools are sprouting up that allow you to more easily write DITA content without dealing with code. But Marlene says that she was on a budget; they opted for a more basic XML editor and actually write all their documentation in native XML. Rather than cumbersome, she says it’s quite easy and only takes about a week before the writers become accustomed to it. The XSLT transforms posed more difficulties, she says, but nothing insurmountable. Read the rest of this entry »