I’d Rather Be Writing - Tom Johnson

You’ve probably heard the saying, when you don’t feel like praying, pray. When you don’t feel like serving, serve. Feelings follow actions, so as soon as you start doing something, eventually you start feeling the desire to do it. But is the same true for blogging? If you don’t feel like blogging, is it time to blog? Read the rest of this entry »

Sebastian asks,

I have been searching the web for information about how to divide workload among writers as the the workload–and the department itself!–grow. I am thrilled to find your blog! I am a new writer in a Health Information Systems doc group. We write for 120 products, maintain 600+ documents (several output formats). Do you know of any effective strategies/tools/medications?

What kind of documents do you produce?

We produce online help, how-to guides, quick reference guides, manager’s guides (procedural content), introductory guides (conceptual content), release notes, configuration guides, known product issues, tutorials…. Read the rest of this entry »

Jane made this cool little Venn diagram the other week.

It’s intriguing and feels true, but it’s meaning seems just out of reach. What do you think it means?

In the on-screen text in WordPress, on the Write > Page screen, I ran across the following help text.

Just yesterday my colleague Ben was asking how I felt about the use of contractions in help. Contractions? We’ve moved far beyond contractions. We’re now using terms like janky.

How I would love to publicly insult the applications I document! E.g., Hey, we know this feature is kludgey, but we couldn’t find an easy fix. Hang on — the next release will get better.

WordPress Training Course
Date: Saturday, July 19
Time: 9 am to noon MST
Cost: $99

If you’re interested in WordPress training, I’m holding a course this Saturday from 9 a.m. to noon MST over the web. Click the WordPress Training button on my navigation bar for details about what’s covered and the cost.

Speaking of WordPress, here’s a great post from Mashable about 20 must-have compatible plugins for WordPress 2.5.

I especially recommend the NextGen Gallery plugin. If you have a lot of photos to post, and you want to group the photos into various galleries, and the galleries into albums, and you want to manage the title and caption text in an easy way, this plugin is amazing. It adds a ton of image functionality to your WordPress installation. For an example of what it can do, view the Gallery and Featured Project page of this site. You can also integrate photo effects like the SimpleViewer from airtightinteractive.com. This is just one example of how WordPress can go far and beyond Blogger and other platforms.

Of course, you may be content with Blogger, Typepad, LiveJournal, etc., and if so, that’s fine. But if you’re frustrated with your site’s limitations and lack of features, the inability to customize it, or you just want to try something new, it’s time to experiment with a self-hosted WordPress blog. This three-hour course can help get you up and running.

A WordPress image gallery allows you to create a sharp-looking presentation for your photos or images. With just a couple of plugins and tweaks and some basic understanding of the WordPress gallery tag, you can make a Lightbox/Slideshowesque display of your gallery images without any custom coding.

Here’s an example of a WordPress gallery that goes a step beyond the default. Click each of the images, and then click the arrow buttons on the image to move to the next one. Instructions for creating such a gallery are below.

Read the rest of this entry »

Woopra is a new website analytics tracking tool that gives you enough live stats to write a dissertation. It takes analytics tracking a step further than Google Analytics and allows you to see a live map of visitors on your site — what they’re reading, what paths they’ve taken, what country they’re from, how long they’ve been on your site, and so on.

If visitors have left a comment and haven’t cleared the cookies in their browser, they even appear in Woopra by name, and you can see them. One reviewer said this capability from Woopra allows you to “stalk your visitors.”

Read the rest of this entry »

How many times have you written a 75+ page guide and heard the customer say, This is great, but can you give us a condensed version?

After the third or fourth time I’d heard this, I decided to actually try it. I wasn’t sure exactly how to lay it out, so I spent a couple of days flipping through magazines — especially WIRED — looking for attractive layouts to copy.

I also needed a better tool than Word, and managed to acquire a copy of Adobe InDesign. After a few days of prototyping and writing, I finished my first one-page quick reference guide.

At the next project meeting, I brought color copies of this one-page version of instructions. The response was overwhelming. You’d think I was handing out free candy. Everyone wanted one.

They immediately started looking it over. In contrast to the pained expressions I’d seen after handing people long manuals, their faces showed incalculable glee. At that point, I knew the quick reference guide was a must-have deliverable for every one of my projects. Read the rest of this entry »

At Borders or Barnes & Noble, I often browse the computer books to see the different ways writers approach help material — especially how they approach the same help material.

The other day I wanted a book on CSS, so I pulled four available CSS books off the shelf and began browsing them. Each book looked respectable, but the CSS Cookbook, by Christopher Schmitt, had a unique format that caught my attention and convinced me to buy it.

In the CSS Cookbook, each topic is formatted with Problem and Solution subheadings. Here’s an example:  Read the rest of this entry »

Rahul Prabhakar, editor of the TechCraft newsletter, which accompanies the Technical Writers of India listserv, published an interview with me in the latest issue (June 2008).

You can read it here: Techcraft e-Newsletter Volume 38 June 2008. It’s in the “Spotlight” section near the end. Read the rest of this entry »

At the end of many topics in Flare’s help, a What’s Next? section appears. For example, in a topic on Creating a Table of Contents, the What’s Next? feature guesses what you’ll want to do next — enable the table of contents in your target. See the following image.

Read the rest of this entry »

Jefferson McClure added a thought-provoking article link on WriterRiver.com titled “Myths of Technical Writing.” The article is by Bob Doyle and appears on the dita.xml.org wiki site here. In the article, Doyle and other wiki contributors mention 4 myths about technical writing: Read the rest of this entry »

In a previous post, I mentioned my desire to use SharePoint as a help authoring platform because it provides a Web 2.0 experience that is company-sanctioned. SharePoint not only has blogs, wikis, and RSS feeds, but also integrates with Active Directory, Outlook 2007, and has integrated search across all content.

However, the more I tried to use SharePoint as a help authoring tool, the more problems I ran into. SharePoint doesn’t handle role-based content very well. For example, if you have administrators and regular users, it’s not easy to create two versions of the same help material. SharePoint does have audience targeting, but only if your audience is already tagged with roles in Active Directory (and if active directory is integrated with SharePoint). Read the rest of this entry »

My site was hacked today. Usually when someone says “my site’s been hacked,” the first response is, are you sure you didn’t screw something up yourself? Yes, I’m sure. Someone twittered that my tinyurl was showing a login page. Actually, for me it showed the install page below:

But I hadn’t been upgrading or installing anything. Something was definitely wrong. Read the rest of this entry »

This past week I had the opportunity to get intimate with Microsoft Office SharePoint Server 2007, aka MOSS 2007. If you’re totally unfamiliar with SharePoint, this post will not get you up to speed. But for those embarking on a SharePoint customization challenge, most likely you’re already familiar with SharePoint. Before you start customizing it, be sure to read these ten concepts and gotchas.
Read the rest of this entry »