March 2008 | HelpScribe

Should technical writers write system requirements?

Writing system requirements can be a daunting task. Most software products are built by teams of developers, and each component of the software may impose different requirements. The situation gets even more complicated if the system requirements must cover an entire product line. Combining all of this information into a comprehensive document is no simple matter.

So who is best equipped to handle such a task? Should technical writers write system requirements? Or should it be left to those who have more detailed knowledge of the software?

System requirements demand communication

From experience, I'd say that getting accurate requirements for each product or product component is the easy part. A good software engineer will be able to provide such details without much difficulty. They may need to chat a bit with others on their team to get the details right, but in the end they should be able to produce requirements for their code.

However, writing system requirements is really about organizing details from multiple developers or product teams into a complete final document that everyone agrees on. This can be a project management nightmare.

Often system requirements will need to be reviewed multiple times by people from many different development teams. Review comments from one team may conflict with those from another team, and getting a definitive answer can be tough.

Your Sales department may voice concerns if the recommended requirements are too high for a significant number of customers. If the software will run on computers that fall below the recommended requirements, more customers can purchase the software. Customer Support will also have essential feedback based on user calls that conflict with the stated requirements.

Legal issues should be considered. If your software requirements mention operating systems or products from other vendors, you will need to include the appropriate copyright information when you mention those products. This task requires research skills.

Communication with your publications department or web team will be necessary when it comes time to deliver the completed system requirements to your users.

System requirements are difficult because they impact almost every department in the organization.

So who would want such a task?

Writing system requirements is about gathering information, organizing it into a comprehensible document, ensuring that everyone agrees on the content, and then handling any pre-publishing tasks before handing it over to the appropriate people for delivery to your customers.

Isn't that what technical writers do every day?

Most technical writing departments will have established relationships with all of the departments necessary to produce system requirements. And an experienced technical writer will have the skills necessary to combine complex technical information into a user-friendly document, handle the politics of a messy review process, and prepare the document for delivery.

Should technical writers write system requirements? Absolutely. But they should do so using feedback from the appropriate people.

System requirements demand a team effort, but they are still documents. And documents are what we do best.

For more tips on writing software documents, see 22 tips for writing software documentation users will actually read.

How to entice users back to the help

I've often wondered how many users visit the help once and then never come back. The statistics would likely be sobering.

There are a ton of reasons why this might happen. Perhaps users can't find the answers they need. Or maybe they just don't understand the purpose of help, or how it should be used. Maybe they've never touched the Help menu to know what options are available.

These are all problems help authors should work hard to address. Here are a few ideas for making help stickier, so users will return again and again.

In your Welcome topic, add content that sells the help to users by listing benefits and features. Then link to tutorial content for using the help. By putting the benefits first, users will be more likely to invest the time to learn how to use help.
Provide immediate answers. Don't make your users dig around to find solutions to their problems. Use context-sensitive (F1) topics to provide relevant information and then link to appropriate procedures.
Clean up your design. Make your help easy to read and navigate so users can focus on the content. Learn CSS and learn the fundamentals of graphic design. Think CRAP - Context, Repetition, Alignment, and Proximity. Read books by Robin Williams (the designer, not the funny guy) such as the Non-Designer's Design Book.
Implement favorites and comments. Let your users write notes to themselves in their favorite topics. By doing so, you give them the ability to customize help to their needs and create a personal investment in the content.
If your product displays a Tips wizard to new users, talk to your development team about adding a tip describing benefits of the help
Link the help to forums, wikis, knowledgebases, and other resources. By making these available from the help, users are more likely to see the help as a starting point for all of their information needs.

While these tips won't give your help the suspense of a Stephen King novel, they just might entice users to visit the help a second time. The key is to keep them coming back. To do that, you have to spoon-feed them relevant and helpful information.

Can help authors afford to ignore Google?

Web applications are slowly eating away at the market share previously held by desktop apps. Forums and wikis are opening the doors to robust user communities. Meanwhile, tools such as Adobe AIR and Microsoft Silverlight are blurring the boundaries between the desktop and Internet, allowing non-connected users to sync up with online content.

The result? More and more content is being moved from local machines to the World Wide Web.

As a result, users are drifting away from product-specific Search functionality and are embracing the power of Google instead.

What will users find when they use Google to search for your help content?

How Google views help

If you are developing help content that will be visible to the world via the Internet, you need to consider the implications.

Just as Internet Explorer was not built as a help viewer, Google was not designed to give special treatment to help content. That means the Google search algorithm treats your help content just like any other web page.

This isn't a bad thing, necessarily. For example, I was recently working with a web application and had a problem completing a task. The product-specific help didn't contain a helpful solution. A Google search, however, provided a help topic for a tool developed by a completely different vendor; a competitor to the tool I was using. My esteem for the competing product rose considerably.

If you are the competitor in this case, Google's non-biased (sort-of) treatment is a good thing. But if your help is insufficient, Google might send users straight to your competition.

If you are considering moving your help content to the Internet, keep this non-preferential treatment in mind. You need to ensure that your help is thorough and that it shows up in search results.

SEO for help authors

SEO, or "Search Engine Optimization," will soon be a common term among help authors. Why? Because in order to avoid it, you have to ignore search engines like Google.

(Ignoring Google is bad. Users like Google.)

So what is SEO and how does it apply to help authors?

In a nutshell, SEO means optimizing your online help content so that the search engines can find the appropriate topics to meet user expectations.

Google uses keywords and page rank to generate search results. This is WAY different from the full-text search provided by most help authoring tools. Your content must include the words your user types into Google's Search field, or at least synonyms that Google recognizes. And, your content must be authoritative enough so that Google lists your help near the top of the results instead of help for a competitor.

Keyword optimization

Keyword optimization can be tricky. Technical writers and consumers often choose different words to express an idea. A user might search on "personal information" instead of "client data" and find nothing in the search results. This is a problem for both ranked search results and full-text search.

Even if Google's search algorithm makes the connection between "personal information" and "client data," chances are your help topic will appear many pages deep, after websites that have nothing to do with your product.

To rank high in the search results, your content should include the exact phrases that users are searching for. This means leveraging tools like WordTracker or examining search data from user forums to find out what phrases users are entering into the search field.

Topic titles are especially important to Google's algorithm. If your help topic titles do not include the exact search phrase, that topic won't rank high in the results. Hyperlinks should also use the search phrase and point to information relevant to the search keyword.

But be careful. If you overuse a keyword in a single topic, you might trigger Google's SPAM filter and your content will not appear anywhere near the top of the search results.

Page rank

If you want your help to be visible in Google, pay attention to your page rank. The page ranking system is fundamental to Google's algorithm. If the URL for your help is ranked highly for specific keywords, your results will appear above those from competitors.

Page rank is determined by a number of factors. The most important is inbound and outbound links. For example, if you are writing help for an audio web application, links from audio websites and forums to your URL will increase your Google clout and bump your help topics up in the search results.

Help authors can leverage existing online content to gain page rank. Putting the help under the same URL as a product forum and corporate website would likely improve the page rank of all three, assuming the content is somewhat related. (Google likes to see a consistent theme.)

Speculation? Perhaps...

I know I'm going out on a limb with this discussion. Most help authors won't need to consider such issues any time soon. And site-specific checkboxes can be enabled so that users can Google only content from your website.

However, many help authors already moving help to the Internet, or are at least considering it.

For web applications it seems the natural thing to do.

And as for those site-specific checkboxes... do you really want a single checkbox to separate you from your competitors? A checkbox that users must remember to click?

When Google provides an answer to a user's question by showing them a competitor's help, that competitor gains immediate mindshare without spending a single advertising dollar. The perceived ease of use for that product increases, and customers will consider whether switching products would make them more productive.

How many customers can you win over just by making your help available via the Internet?

And how many customers can you afford to lose when your competitors provide the answers?

Thoughts, anyone?

Powerful peer review strategies

If you work regularly with other professional writers, chances are you've had the opportunity to peer review their work. This can be a challenging task. How do you find something valuable to add when the writer has excellent writing skills and a firm grasp of the content?

Here are a few things you can look for in addition to grammar and copy editing issues.

Incomplete or poorly organized content

The writer and SME will have read through the document many times. As a peer reviewer, you have a fresh perspective of the content. This may allow you to see areas that could be fleshed out more thoroughly or restructured for improved clarity.

Are any important details missing from the document?

Do you have unanswered questions after reading through the text?

Did the procedures match the logical order of the process, or could they be rearranged for greater clarity?

Keep these questions in mind during your peer review, and try to see the document from a user perspective.

Unexpected results from procedures

Sometimes two people can get different results from the same procedure. This is especially true when working on software documentation. Differences in the software settings on two machines can impact the data, and can produce entirely different results at the end of a procedure.

Perform all of the procedures during your peer review and compare your results to those described in the document. You'll help the writer catch any unexpected deviations so that users won't have to struggle with them.

Compliance with recent convention changes

If you work on a large documentation set, chances are your conventions will differ a bit for print documents, help content, white papers, and so on. Product names may change due to acquisitions or new marketing strategies. Boilerplate text may change based on decisions from product managers. All of these changes can be hard to keep up with.

Peer reviews are a great opportunity to ensure that a document is consistent with all recent convention changes. Even the best writers will miss these changes now and then.

Spell-check failures

For most technical writers, spell checking is as automatic as brushing your teeth in the morning. However, spell check doesn't catch everything.

For example, a spell check won't change "there" to "their," or "principle" to "principal." If a set of human eyes doesn't catch these mistakes, they will show up in the final product. Peer reviews are a great opportunity to fix them.

Random formatting issues

Authoring tools don't always format content in the most predictable manner. Pages will break at inappropriate places. Footers and headers will differ across sections. Tables will split across pages.

You can assist the writer by searching for such issues during your peer review. Make a checklist of common formatting issues that result from such tool struggles and use the checklist to guide your review.

The next time you get the opportunity to peer review another writer's work, try to search for the issues mentioned above. These guidelines should help you provide some useful feedback.