If you're integrating code examples into your technical documentation, a couple of tools can help with this. If you have an online output, you can use Code Prettify (see its Drupal version or WordPress version or regular HTML page version). This module/plugin applies syntax highlighting to your code so that it's more readable. I usually replace the angle brackets with their character symbol equivalents (< and > for less tha...
In my previous post, I wrote about how handy collapsing and expanding sections can be. Although there are several plugins that enable this functionality, it's pretty easy to create this functionality yourself from scratch. JSfiddle.net is a neat site that lets you play around with JavaScript, separating out the HTML, CSS, JavaScript, and result into their own quadrant on the page. I created a "fiddle" showing the HTML, CSS, and JavaScript...
After my post on Organizing Page-Level Content, a couple of people asked me about the usability of collapsible sections, also known as content toggles or dropdown hotspots. These are sections that are collapsed upon initial display and then expand when clicked. You can implement collapsible sections in several ways. In Flare, you can insert drop-down hotspots from a quick button on the ribbon. In Drupal, you can use the Collapse Text modu...
I have a few bad habits I'd like to break. One of those habits is crashing on Friday nights. After working all week, I tend to crash around 8pm and let my brain cells go dormant for a few hours watching mindless television. When the morning comes, I open my sleepy eyes and wonder why I wasted all that time the night before. If I could get those hours back, I certainly wouldn't spend them watching TV. Productivity is a perennial topic for ...
One of the topics I haven't covered is how to organize content within the same page. If your topics become long and look more like Wikipedia pages, you will have a lot of content to organize -- potentially twenty different sections on the page, including both tasks and concepts. What's the best way to organize all your page-level content? Although many users, being action-oriented and looking to do something, may skip straight to a task, ...
During our move from Utah to California, we had a lot of things to do – preparing our house to rent, packing, loading, driving, finding a place to rent, unpacking, and the million tasks in between, such as researching areas, renting a truck, and navigating directions. As I have four children under the age of 13, there wasn't much for them to do, and they kind of had to spectate and wait and watch as we moved. We've never encouraged video ...
The most common questions I get on my blog are questions about finding jobs in technical writing. While looking for jobs the other month, I realized a few things that I haven't actually recommended before. Here are a few notes from my recent job search: Large companies often select candidates to interview based on employee recommendations. I have a lot of connections with tech writers (784 on Linkedin), so I had quite a few people who he...
Big changes are in store for our family. We're moving from Utah to California, and I'm starting a new job in Redwood City (which is in the San Francisco Bay area) at a company called Badgeville. Badgeville is one of the leading companies in gamification, which is the practice of incorporating game dynamics and techniques into non-game settings to influence user behavior. I'm really excited about the new adventures and opportunities ahead...
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...
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...
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 ...
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...
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...
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...
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 ...
