A Few Software Tips to Make Technical Writing Easier

by Tom Johnson on Aug 18, 2009
categories: technical-writing • screencasting

LugIron recently praised a video response that a vendor made to a customer, calling it "an outstanding example of Social Documentation at work." The customer loved the video, especially given that it was personally created by the company founder.

Ten years ago, such a quick response wouldn't have been possible except at a large time cost from the company. But with the software tools today, even sharing multimedia documentation is somewhat easy. It's no longer an ordeal to make and publish a video, or a website, or deliver help content in almost any form to the consumer.

Reading LugIron's post prompted me to reflect on the myriad ways software is making our lives easier as technical writers. Here are ten ways I'm using software to lift the documentation burden and deliver help faster and more efficiently to customers:

Jing. I use Jing to log bugs when the bug is a you've-got-to-see-it-to-believe-it kind of bug, or when it's just faster to capture video than describe the quirk. I also use it, on occasion, to provide quick support responses to customers. You can configure Jing to auto-publish to a specific location, such as a SharePoint drive, so that the sharing of your videos is literally a five-click process.

SnagIt's quick styles. The quick styles feature available in SnagIt 9 allows you to define an object type and save that style so you can quickly access it again. If you're drawing little diagrams or creating screenshots with the same circles and arrows, the quick styles feature can save you from having to customize the shapes each time.

SharePoint hosting for my webhelp. I no longer package the help with the applications, but instead host it on SharePoint, where I can update it on the fly whenever necessary. This saves me from the hassle of nagging developers to push out another version release to update the documentation, and it gives me complete control to update, modify, add, remove, or otherwise tweak the documentation as needed.

Flare's Publish feature (includes built-in FTP). When I update my webhelp, publishing the update to replace the existing webhelp file on SharePoint is a one-click process with Flare's built-in Publish feature. I don't have to copy and paste the files into Windows Explorer session that I open up over an intranet page. It's just a one-click-and-done kind of task.

Flare's relationship tables. I just discovered relationship tables a few weeks ago, and it greatly simplifies related links by allowing me to manage all my links in one convenient table.

Native file formats in InDesign files. Rather than exporting or saving images as PNG or GIF or JPG, I keep them in their native PSD or AI formats and insert them as linked images in InDesign. This way, when I need to update the file, I just right-click the image and choose to edit the original. It saves time and looks crisper.

Flare's task review feature. When I need to have a colleague review one of my help topics, I use Flare's built-in topic review feature to send it to my colleague, and he sends it quickly back. I don't have to manually copy and paste or print out or attach the file to get it to him, and I can import my peer's annotations directly into the original file in a side pane for easy viewing.

RSS feeds from JIRA. The project team I'm on uses JIRA to log and track bugs, and there are hundreds of bugs in the system in various states at any given time. Rather than manually sort through the list, waiting for each item to load to see the details, I installed the Sage plugin for Firefox and added the RSS feeds of all the bugs I've logged as well as other relevant JIRA feeds to this Sage reader. With one click, I can see a quick overview of all the bugs and scroll quickly down to read the latest comments and statuses.

Microsoft Communicator. Communicator is Microsoft's instant messaging client, and it ties in with Active Directory to show you presence indicators of who is online and offline based on their computer activity. Customers, developers, project managers, and team members contact me all the time using Communicator. The IM conversations are quick, efficient, and save time from lengthier interruptions. I can also carry on multiple tasks at once while having a conversation on Communicator.

SharePoint Team Blog. Our team regularly communicates using a SharePoint team blog. We're a team of eight people, many of whom sit in different buildings and floors. Apart from our once weekly team meeting, we don't interact much in person. But our SharePoint team blog can be a hot bed of interaction, with several posts a day and sometimes up to a dozen comment exchanges. The posts are often short, with requests for feedback, or new ideas or problems to solve. The blog helps us meet virtually to find answers and in turn be more productive in our work.

These are just a few of the ways that software is lifting the documentation burden and helping me be more efficient. I doubt I'll ever have a streaming video channel on ustream, but that's not really how I see my role as a technical writer anyway.