Does Topic-Based Authoring Help Readers As Much As It Does Writers?

topics2

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

Many large companies have adopted a modular, topic-based approach to technical documentation. This is mainly because content can be reused in various ways from a single source, preventing multiple versions of the same information. This approach helps writers publish the same information in different combinations to different media (for example, mobile devices and TV screens).

Does topic-based authoring also help readers? In a number of ways, it does.

Structured content helps readers because the format and approach are consistent, therefore it is easier to use and understand, even when it is accessed from an index or search.

Standalone topics are based on their content type: tasks, concepts, and references. For example, tasks provide the steps necessary to perform a specific goal; concepts provide a way to understand how that goal fits into a larger scheme of information; and references often provide alphabetical lists in tables, such as a command options list.

Separating descriptive information from task-oriented information helps readers access only what’s relevant to them. Topics provide just enough detail for readers to understand the content contained in each one without having to look somewhere else.

Linking related topics is an important part of modular documentation. Links help readers navigate, and the information they find will be exactly the type of information they need. If different topics are written by different authors, readers should still be able to navigate efficiently through the content to find what they’re looking for. For example, task topics almost always have related concept topics, reference topics are referred to by multiple concept topics.

Mark Baker, who writes about developing task-oriented, topic-based content in his blog Every Page Is Page One, points out that “breaking down content into small structured units is a good way to improve consistency and productivity.” Topics help readers, he says, when they include context and links. “Context can be a sentence or two that helps readers figure out what the topic is about and how it relates to other topics, for example, what it covers, what release it applies to, and what type of information it is (task, concept, or reference).”

So perhaps the answer is that what helps writers also helps readers.

Have something to add? Please share it in the comments.

Technical Writing Tools: Help Authoring

HelpButton

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

The most common reason for a user to look at an online help file is to find an answer to a specific question. The most important aspect of a help file is accessibility of the information it contains. Help files range from small, simple “read-me” files with very limited information to hypertext-based documentation.

First Steps

  • Identify topics: Help files are designed to work in conjunction with other types of documentation to form a complete information package. It is the task of the developer or technical writers to identify the help file topics. The best way to do this is to analyze the product. Then, once you have identified all of the topics, separate them into related groups.
  • Create a structure: Once you have identified the topics, you can start structuring the help file. Although the structure can depend on the software, the main purpose of the help file is to provide quick access to specific information. You can achieve this goal by using a simple content tree and keywords to build the help file index. Typically, the content tree should not exceed three nesting levels, although you can use two levels for small files that contain short topics and sub-topics.
  • Design: Design a structure that does not change often, even if information for a specific topic changes. Create a modular and flexible help file that can be used for the next version of the software. The HTML file names should remain stable. If the help tool allows it, it would be good to have a method of differentiating the various HTML files of the same name.

Creating a Help File

  • Access: A help file is not read in the order it is written, so make sure the most important information is accessible from accessing it in multiple ways. For example, the introduction page might never be read, while other information might be accessed by the index directly without the use of the content tree. If a specific topic is discussed in another part of the file, create a link to help users access the related page.
  • Content: The most important part of a help file is its text content. Even if you use graphics and formatting to make a point, the help file will be ineffective if the text is limited.
  • Hypertext: Provide links for users who are interested in knowing more about a specific topic. The most important rule is to make sure the links are actually relevant and useful. With this in mind, it is probably better to use too few links than too many.
  • Keywords: Prepare a list of keywords that are related to the specific HTML pages of the help file. Some users like to browse through the content tree, but others go directly to the index to find the topic by keyword.
  • Size: It’s not a good idea to create a smaller file by limiting the information included in it. A help file should contain everything necessary to use the software and solve simple, typical problems. This means the size of the files can vary from very small to 15 MB and more.

Have something to add? Please share it in the comments.

A Guide to Careers in Technical Writing

Technical_TypingWritten by Allan Hoffman

To some people, any job with the word “writer” in the title looks like it must be a blast — the next best thing to working on episodes of “Mad Men.” If spotting the job title Technical Writer in your job search whets your appetite to learn more, here’s a guide to the profession.

Is Technical Writing for You?

“If your goal is to write a novel, this is not the job,” says Saul Carliner, a former president of the Society for Technical Communication (STC). “Although the finished product is something you wrote, there’s a lot of collaboration. You’re interviewing people. You’re coordinating. Twenty to 30 percent of your time is writing.”

Contrary to what many assume, working as a technical writer involves much more than sitting alone at your PC. The job requires plenty of contact with technical professionals, from programmers and project managers to machine operators and medical technicians. Solitary? Not quite. Collaborative? Most definitely.

If you’re considering a job as a technical writer, one way to learn if it’s for you is to spend several hours reading and reviewing computer manuals and online help systems, like those for your operating system and assorted applications. Ask yourself a simple question, Carliner suggests: “Is writing this what I want to do for a living?” Also, remember that companies use most technical documentation for internal purposes — no one in the outside world will ever see it.

But the field has broadened to include a variety of job roles and responsibilities, as the name of its leading professional organization, the Society for Technical Communication, suggests. Technical communicators write and edit technical manuals, but their work may also include producing online tutorials, web-based training, and other materials for industries ranging from healthcare to manufacturing.

And the pay? According to the Bureau of Labor Statistics, the median technical writer salary was $64,610 in 2011.

What Background Do You Need?

As a group, technical communicators come from varied backgrounds. According to an STC membership study, the five most common academic backgrounds are English, technical communication, science or engineering, computer science, and journalism,. Anyone with a technical background will have an easier time breaking into the industry, as it shows a facility with technical topics and the ability to work with industry professionals. Consider taking courses in the following topics to build a foundation:

  • Technical Writing: Typically offered at colleges and community colleges as a way to gain an overview of the field and develop writing samples.
  • Web Design: A way to gain an understanding of design and presentation issues.
  • Programming: To help you gain a better understanding of how software is created.

Do You Need to Know Specific Programs?

You should know Microsoft Word, if you don’t already, and you’ll be better off if you’re familiar with FrameMaker or RoboHelp, two programs often used for writing technical documentation. Knowledge of Web production tools also is an asset.

Can You Move into Other IT Jobs?

Technical communicators often move into jobs as programmers, systems analysts, information architects, and project leaders. Others shift into sales or management roles.” It’s a great way to get into an organization, and then move into a different job,” says Carliner.

Whatever your goal, the more technical know-how you acquire, the better. Throughout the information technology world, people who have superior communication skills and can hold their own with die-hard techies command a premium.

How Do You Get Experience?

Budding technical communicators should seek out internships, volunteer work, and other opportunities to gain experience and build a portfolio of work in the field. You will have a tough time finding a company willing to consider you without writing samples. Consider volunteering your services as part of an open-source project to demonstrate your ability to work on a team and translate technical matters into plain English.

Have something to add? Please share it in the comments.