September 2010 | HelpScribe

6 ways to improve your help authoring workflow

Technical writing isn't just about producing documents -- it is a business function. For most of us the ultimate goal is to increase the overall profitability of our organization. By increasing the efficiency of our help authoring process we can be more productive, reduce costs, and maintain our sanity by automating tedious tasks.

Here are six ways to improve your help authoring workflow.

Use snippets - Any time you see a similar section of content in multiple topics, consider converting it to a snippet. That way you only have to update the content once to have those changes flow to all topics that include the content. If you use MadCap Flare, check out the Snippet Suggest feature in Analyzer.
Create online schedules - Use a collaborative scheduling tool so that everyone can stay updated on deadlines. Create a schedule for your project, send a link to all stakeholders so they can approve the schedule, and then create reminders for all deadlines (review dates, delivery dates, and so on).
Streamline reviews - Use document management software and Adobe Acrobat to facilitate reviews. Document management tools allow you to upload documents to a server, route the documents to reviewers, and track revisions. Acrobat allows multiple reviewers to make comments in the same PDF file, and you can print a comment summary when it's time to incorporate the changes.
Automate your help delivery process - Some HATs, like RoboHelp, offer a command-line option for generating output. You (or a tech-savvy coworker) can author a shell script or BAT file to launch your HAT's compilation process, prepare the output files for delivery, and copy them to your QA server or delivery location. You can automate the archiving process in a similar manner. WinZip offers command-line features for zipping up your project files so they take up less space in your archives.
Create email templates - If you are constantly emailing others to assign reviews or inform them that help files have been delivered, consider creating email templates that contain boilerplate text for each kind of message. Not only will this save you time, it will also remind you to include all of the important details. (I picked up this trick from a savvy manager.)
Share with others - By sharing the scripts, templates, and other time-saving tools with others in your department, you can increase the overall productivity of your entire team. This is a great way for technical writers to directly improve the company's bottom line and leave extra room in the budget for better tools and fun stuff like catered lunches, expensive coffee, and trips to the bowling alley.

Hopefully these tips will help you spend less time struggling with your help authoring workflow.

Small business information management strategies

The amount of information modern businesses collect and distribute can be overwhelming. Even for smaller businesses, poor planning can have a negative impact on efficiency and scalability. By creating a solid small business information management strategy ahead of time, organizations can improve productivity and profits on a daily basis. Here are some tips for building such a strategy.

Information architecture should be scalable; by building a strict architecture, management over the long term becomes easier. Such a system will take more time to develop, but should lead to increased efficiency.
Small businesses often have limited resources; also, they often have less information to manage compared to large corporations. They should choose tools appropriately. Enterprise-level content management systems and similar tools will likely not be cost-efficient, especially when maintenance is considered.
Decision making tools, such as flowcharts, can help people react to situations without the interference of judgment and emotion. Take the time to develop these tools if they would be beneficial to your workflow.
A formal process for documenting new business information and categorizing it will improve retrieval. Such a process should be built upon a solid architecture. Spend a bit of time researching metadata and consider how to categorize your information so that you can generate accurate reports to ease management.
Information security policies should be set in place at the outset. Limiting the availability of information to those who need it can reduce long-term management requirements. Key issues are securing information that is only appropriate for certain audiences, limiting the ability to alter information to only approved individuals or groups, and limiting information loss.
Archiving and other preservation concerns should be addressed by the architecture and tools, and enhanced by writing policies and procedures. Automating the archiving of documents builds additional safety into the overall information management schema.
A small business can often model larger organizations; however, they should watch for architecture elements that will be inefficient and unnecessary considering the scale of their day-to-day operations and overall information needs.

Remember, the overall goal is to provide information to those that need it in a timely and efficient manner. The information management process should be as automated as possible so that your small business can operate more profitably.

Which kind of technical writer are you?

When you work in a large technical writing department, it becomes very obvious that we all have different strengths and weaknesses. A great manager will hire writers with different skills to increase the overall effectiveness of the team. So, where do you fit in?

The Writer - You wait for enhancements like a kid watches for Santa on Dec. 24th. When they arrive, your word processor barely manages to stay one step ahead of your fingers and the carpet between your cubicle and your SME's loses another layer. Grokking the new features and turning them into instructions is what you do best, and if you weren't a technical writer you'd probably be a teacher or trainer. Specs? You're on it!

The Editor - You are an expert at slicing and dicing shoddy content and turning it into clear and concise text that flows like honey on a hot biscuit. Your waste basket is filled with empty red ink pens, and your inbox is filled with review requests because you've built a reputation for turning rough drafts into works of art.

The Techie - You go where others are afraid to tread... under the hood of your complex authoring tools. When things break, people knock on your cubicle door. The boss wants a custom ASP page for gathering feedback on server-based help? You offer it up the next day, including a back-end database and reporting tools. Easy as pie, as long as the coffee pot remains full.

The Socialite - You are the information highway for your department. When enhancements creep into the software, you know about it ahead of time because you work out with the developer and watch her pets when she's out of town. The team is having trouble getting feedback from a product manager? Not anymore, she's already on your Christmas card list and smiles whenever you knock on her door. You are a master networker and you never eat alone.

The Project Manager - You've never missed a deadline, thanks to your cross-referenced Gantt charts and systematic approach to getting the job done. You grease the wheels and keep productivity running on high at all times. Delays? Not on your watch. As long as your email software stays up and running, business will keep on rolling, because Organization is your middle name.

So, which kind of technical writer are you?

Technical writing unchained - a custom approach to help authoring

After a decade of writing documentation for high-quality products using robust authoring tools, I've often wondered... what approach would I take if I was doing this just for fun, with no restrictions? What if help authoring was my hobby?

It's a rather insane idea: technical writing as entertainment. But I haven't hit my head, or quaffed one slushy too many (although I've suffered many cases of brain freeze). Remember the personal computer industry 25 years ago? When computer users were geeky college kids who spent three hours typing in machine language to make a ball bounce across the screen? It was about fun. And where do you think all of those Unix MAN pages came from? Hobby computer geeks writing for the sheer fun and glory.

So, let's say I'm building a help project for fun. How would I equip myself?

Right off the bat, I'd throw out my HAT. (Sorry, the rhyme was completely unplanned.) Not because they are bad; in fact, robust tools are essential for multi-author environments where efficiency is key. But if I'm doing this on my own, I don't need the headaches that come with an integrated tool set, nor could I justify the expense. (It isn't that fun of a hobby.)

Why choose small tools? Big programs tend to crash more. (That's a generalization, but a good one, I think.) Small, specialized programs would allow me to author my help project without the hassles caused by all-in-one solutions. And I can get the tools for free.

All output features, such as navigation, I'd build myself.

My project would consist of a well-structured set of folders, similar to the output you get when you generate browser-based help.

I'd start by installing Notepad++, including a spellchecker plugin. Seriously, if I'm going freestyle, all I need are line numbers. Bells and whistles, drag-and-drop, and WYSIWYG tools are great if you're drinking the HAT kool-aid, but I've always preferred working under the hood. (Maybe that's why my help authoring tools crash often. You can't hot-rod them the way you can a 1970 Chevrolet and expect everything to run smoothly. I've tried, with only limited success. You can't just "bolt on" some extra subroutines.)

Next, I'd install Perl. Perl is like a Swiss army knife; when you need a can opener, it can get you pretty close. I'd use Perl for global search and replace, reporting, and for auto-generating navigation components, which I'll talk about in a bit.

Last of all, I'd install a link checker. Xenu's Link Sleuth is good, and produces very thorough results.

Now the fun begins. After editing my topics in Notepad++, I'd run a home-brew Perl script to auto-generate a collapsible table of contents based on topic titles. A meta-data tag embedded in each topic would tell the script whether to include a topic, and where to put it.

I'd hard-code my index, or build it from meta-data tags, but with careful planning and selection. There's no better way to do it. An index needs to be created manually in order to be really useful. Readers don't think like computers.

Here's where it gets interesting: Search functionality.

For search, I'd install the Google Adsense search tool. Why? Because nobody knows search better than Google, and their algorithm is incredibly advanced. It's like tapping your help project into HAL 9000 or something. People will find what they are looking for.

Also, this is a hobby project, so why not make some money from it to fund future projects? Awesome search plus free cash? I'm sold.

For analytics, I'd do the same. Google Analytics would let me fine-tune my keyword usage based on actual search behavior. That way I can optimize the findability of my help topics. Also, the bounce rate would tell me whether my content is really addressing the needs of users. (This can get tricky. See this post on using analytics for documentation for details.)

Last of all, for quick-and-easy compilation, I'd daisy-chain all of the Perl scripts into a Windows shell script or BAT file so I can build the whole kaboodle with a simple command.

That's it. That's how I'd build a home-made system for authoring help.

Maybe one day, in my vast amounts of free time, I'll give it a whirl on an open-source project. But I'm guessing others have blazed this trail already and still have the results archived on a floppy disk somewhere. If that's you, I tip my hat in your general direction.

The Boss hates your document! How to fix it

You've spent the last month as a contract worker struggling with a tedious user manual. Finally, you create the PDF, hand it over for delivery, and head home with a feeling of satisfaction. But... to your horror and surprise, you find it sitting on your desk the next morning covered in red ink and a note from your boss.

What do you do?

First, don't panic. This often happens as a result of miscommunication, and can be cleared up without too much trouble. Technical writing requires a bit of political savvy, and now is the time to leverage your interpersonal communication skills. (Or, if you've joined the dark side, some shady tactics for tricky office situations. But once you go down that path, you can never return... Bwah hah hah!) Sorry, where was I? Oh, yes...

Bury your feelings of resentment, take a short walk, and then read through the comments. Are they sensible and straight forward? If so, incorporate the changes and redeliver the manual. If not, ask the boss for a meeting.

During the meeting, talk about what exactly when wrong. If there are major problems with the scope of the manual, be sure to get a clear sense of what needs to be changed before you leave the meeting. That way you can address those issues and produce a user guide that is closer to the mark. You don't want to end up in the same situation a second time.

If you disagree with the changes, don't be disgruntled. It's a job, and your boss has the final say. Finish the job and move on.

You may find that there is some doubt about the value of the manual. If you sense this is true, bring the issue up for discussion, but do it in an objective manner. Don't take it personally. Take some consolation from the fact that you did your best, whether the manual is shipped or not. Your job is important.

If the revisions requested by your boss will require further communication with SMEs, be sure to explain the situation to those SMEs openly. Ask them for a bit more time, and be flexible, because they are probably working under deadlines just as you are. A spirit of cooperation will help you get through the job.

Just keep moving forward and stay positive; you'll get through it. And when you finally finish the project you'll have an even greater sense of accomplishment and relief.

This simple trick can make your documents more engaging immediately

Technical writing is generally boring. Not so much the process, but the documents themselves. We can plunge into an endless debate about whether writers should inject humor or other elements to pull readers in (I say Yes!), but maybe there's a simpler answer.

For example, there is a sure way to make technical documents easier to read without making them sound less professional. Novelists and poets are well aware of this strategy, because they focus relentlessly on style. What is this strategy?

Simple... vary your sentence length.

Long, monotonous sentences filled with technical details are mind-numbing. Why not break things up a bit?

Varying the length of paragraphs and sentences has a subtle impact on the attention of readers. It forces their brains to constantly adjust. Without this change in pace, the monotonous rythm of your content will lull readers into a coma faster than a hot toddy and a lullaby.

For example, let's look at the following sentence.

The archive feature allows you to store unused data collections in an efficient manner. Archives can be stored in multiple formats depending on several factors. These factors include the size of your data files and the storage devices available on your computer. Archived data can be retrieved at any time using the Restore function.

Seriously, that's boring stuff. Let's see if we can adjust the pace to make it easier to read.

Do you have unused data in your system? The archive feature can help. When you create an archive, your data is compacted and then stored to the media format that you choose, based on the size of your files and your available hardware.

Don't worry; you can restore your archived data at any time.

Ok, so it isn't exactly "Madame Bovary." But you get the point. You can supercharge a dull sentence without adding knock-knock jokes. All you need to do is experiment a bit with the length of your sentences and paragraphs.

Technical writing does not have to be boring.

7 tips for technical writing students

Fifteen years ago, I was a sleep deprived student slogging my way through a technical writing program in hopes of finding a job. I didn't really know what it was like to work in the field; however, I knew I enjoyed writing and that my love for poetry wasn't going to help cover my college expenses. In other words, I was just stumbling through, like so many students. If I had to repeat the process, here is what I'd do differently.

Network heavily. University professors are well connected. A student can make valuable connections by demonstrating a willingness to learn and be dependable, and then asking professors for career advice and introductions to contacts. Professors are usually glad to help students who ask and put forth honest effort.
Work on projects. Assisting with any relevant project for the university, such as updating a website or editing student resumes, can help you build your resume. Focus on both skill development and creating a portfolio.
Connect via LinkedIn. Start making connections with other students and keep in touch with them. When you find yourself looking for a job, these contacts may come in handy. Don't just network with fellow writers; also keep in touch with computer science and engineering students, because they might be the future product development managers who need your services.
Take advantage of resources. Universities have great libraries, computers with network access, writing labs, career centers, and other facilites that can really help you with career research, job hunting, and building your skills. You are paying for them, so why not make the best use of these resources?
Attend industry-related events. If your English department hosts conferences, invites professional speakers, and so on, be sure to attend. These events will expose you to new ideas from professional technical writers.
Don't focus on the degree. A degree might get you a job interview, but it is your passion and knowledge that will get you hired and propel you through the ranks. If you are only there for the paper, you are wasting your money. When you graduate, you will be one of many job seekers with a degree. What sets you apart? Focus on building your expertise and developing a reputation as a professional.
Don't stop learning. Just because you've completed your degree doesn't mean you have learned everything necessary to be effective and stay relevant. Take advantage of online technical writing programs to continue building your skills after college. Also, get involved with industry associations such as the Society for Technical Communication so that you can stay up-to-date on industry trends.

You put WHAT in your user manual?!

Ok, so I cheated and chose a title for this post that would grab your attention. But there's a good reason. You see, writing a user manual is a tricky business. You have to inform your customers in an accurate way, and help them struggle through any tedious tasks.

But...

That can't be all you do. If you don't put in any effort to engage your readers, you may just lose your most important customers.

Think about it... most of us are just putting out fires. We get into the habit of writing documentation that has a highly professional (ahem... "boring") tone, and we write it in a very disconnected manner because most users just want a quick fix. I've been guilty of promoting this approach myself, because it does meet the needs of many users.

However, it doesn't meed the needs of the most important users of your products.

For example, I know a certain kid who loves video games. When he gets a new game, the first thing he does is read the manual from front to back. That way, when he begins playing, he already has a full understanding of that game. It immediately increases his ability to play the game to its fullest, and appreciate it, even if the game is complicated. In other words...

...he becomes a power user.

...he becomes a product evangelist.

...he becomes a loyal customer because he experienced the full potential of the product.

If a user manual isn't written in an engaging manner, how many potential power users are you sacrificing? Sure, you'll get some people back on track using basic features, but will any of these users ever develop a full understanding of more complicated features without reading overview information?

Give users a full and engaging story to understand. Or expect that they will only ever have a partial understanding of your product, and less loyalty when a competing product crosses their path.

If you enjoyed this, you might also like: 22 tips for writing software documentation users will actually read.