Two Competing Help Models: One-Stop Shopping or Specialized Stores?

I spent the past week in California, interviewing with various companies. In preparation for each interview, I studied each company's documentation as best I could. I noticed two main trends. Some companies group all their documentation together into one massive site. The sites usually have a robust table of contents and include help for most of the company's products. In contrast, other companies segment out their help into smaller sites...

Single Sourcing and Redundancy

Although we have a lot of single sourcing tools, and the term single sourcing is used constantly in tech comm conversations, I've never had a firm answer to the following question: How should the print output differ from the online output? Let's assume that you have all your content in a help authoring tool. You have two outputs configured: an online help and a PDF manual. Should the two formats contain about the same content? This questi...

How to Get Programmers to Change User Interfaces

I received the following question from a reader: Hi Tom, I absolutely love your column and feel as though you are writing for me. I was wondering if you could devote an article, or maybe you already have, about how to approach programmers about their screen designs. Our company has three totally separate divisions that focus on different things. I've just been moved to a different division, and I've found the programmers in this division ...

Four Less Common Types of Technical Writers Companies Are Looking For

Less common roles companies are looking for (photo from Flickr) This week I had an interesting conversation with Scott Abel, The Content Wrangler. He mentioned that he recently surveyed around 500 companies (many in Silicon Valley), evaluating their needs and the kinds of technical writers they're looking for. In addition to skill sets that you might expect, such as needs for writers who know structured authoring, XML, and DITA, companie...

Import DITA Webhelp Output into WordPress

Author in DITA, publish in WordPress 1.0 → Import DITA Webhelp Output into WordPress 1.1 Author in DITA, publish with WordPress 1.2 Challenges in using WordPress for publishing DITA content 1.3 Using WordPress natively for single source...

Single Sourcing Screen Captures to Print, Online, and Mobile Using Flare and Capture

The other week my colleague asked me to write down a few notes about how I handle images with Flare. I realized there's a lot to know about images, especially when trying to single source them both to print and online outputs. In this post, I'll jot down a few of the more tricky points when it comes to single sourcing images. Dimensions Before taking a screenshot, the first question to ask is what dimensions to use. You want to figure out...

Looking at Search Analytics to Improve Help Content

No help strategy can be complete without including regular analysis of search analytics. Search analytics are the metrics about how users access to your help content. For example, some key search analytics include the number of page views for each page in your help, the length of time each page was viewed, the bounce rate, and so on. I use Adobe Site Catalyst (Omniture) to track the page views, paths, and other web analytics information ...

Top 10 Most Frequently Asked Questions about Technical Writing

1. What technical writing tools should I learn? 2. Should I get a technical writing degree or certificate? 3. How do I get a job in technical writing without experience? 4. I’m interested in technical writing, but isn’t it boring? 5. Would I be good technical writer? I don’t have a background in technology or writing. 6. I don’t have money to buy the tools, but all technical writer jobs seem to require knowledge of these tools. ...

Connection Points with the Tech Comm Role

I've noticed a trend lately in the role I play as a technical writer, but I'm not sure if the experience is common enough to be similar to other technical writers' roles, or whether it's just a role unique to my work. I have felt more and more that I'm becoming a "connector." This is both good and bad — but mostly good. Here a few ways I connect people at work: A lot of our users interact through an online forum. We try to drive a lot of ...

Girl Scouts Painting and Comic Art Badges

A couple of weeks ago, we decided to enroll out girls in Girl Scouts. It turns out there's a Girl Scout office in American Fork, Utah, and numerous active troops in the area. This week we focused on the Painting badge (Brownies) and the Comic Arts badge (Cadettes). For the Painting badge, Callie had to create several different types of paintings: still life, a mood, a painting that uses natural objects as brushes, and a mural. For the Comic Ar...

Discovering Girl Scouts

We recently discovered the Girl Scouts program. I have a colleague whose wife used to work for the Girl Scouts, and I've talked to her about it several times, so the program has been on my mind for a while. But we just haven't made the right connections to get involved. I wasn't sure there was an office or troop nearby. Then we discovered an office in American Fork, and it turns out there are a quite a few troops nearby as well. We joined righ...

Create a Child Theme to Customize a WordPress Theme

If you're customizing a WordPress theme, it's best to create a child theme out of the WordPress theme. With a child theme, you can update the parent theme when updates are available. Any customizations you make to the child theme will be retained. Here's how it works. If you'll be creating a child theme for the Twenty Twelve theme (whose folder in wp-content/themes is "twentytwelve"), create a folder called twentytwelve-child and upload ...

Message from Sponsors — January 2013

Talk Plugin for Atlassian Confluence If you use Atlassian Confluence for creating documentation, you might have noticed that it lacks something that is essential for technical writing — a reviewing feature. Talk Plugin can fix that. Talk Plugin for Confluence allows you to leave your comments everywhere on Confluence pages and blogs and take part in discussions with your colleagues. Moreover, Talk can save you a great deal of time with it...

Reader Question: "My Wish List for Technical Writing Tools"

I recently received a comment from a reader who sent me a wish list for technical writing tools. Sam from Canada writes, Hi Tom, I've been enjoying your posts along with Mark Baker's. You both have good points about technical writing trends. I could be totally wrong, but maybe it's not the tech writers that are resisting change. Maybe it's the companies making the tools/money that are resisting change. I can't believe I'm the only writer ...

Moving Between the Agora and the Desert

I had a conversation with a developer the other day about help material. He said that when he sees static pages, he assumes the content is out of date. He prefers forum threads because he can see the dates, and because forums contain real information from people using the product. He likes wikis because he can easily check to see when the information was last edited and by who. One concern he had in our migration away from wikis to a help...