Documentation
The software industry is booming, with more developments than many thought to be possible – or necessary. With desktops, laptops, tablets, servers and other systems, software has become so pervasive that it’s nearly invisible to the everyday user: We just use it and move on with our lives. Behind the scenes, companies understand how technical writing supports software development and usage. With proper software documentation, a user can understand not only how to use and manage their software, but also how to fix potential problems or overcome hurdles while using it. (more…)
What can technical writers teach and learn from others? Plenty, it seems. Will Kelly is a technical writer who maintains a technical writing blog in his spare time.
In a March 13, 2011 post, he described his process for writing technical documents. For those looking for ways to improve their writing or begin to assess their technical writing team, this can provide a simple outline of how the writing work can be managed.
This is the outline that he follows, depending on the final product he needs to create:
(more…)
Part 1 of Structure and Technical Writing look at the ways in which consistent structure in technical writing can be vital to the usefulness of a document. As you create a structure that is consistent, users will be able to pick up the document, find the information they need, and apply it as needed.
Part 2 is intended to solidify that importance and take a look at a few special structure approaches you might use in developing consistent standards for your documentation.
Special Structure Approaches
When structuring a technical writing document, it can help to use:
- Bullet points – Creating lists of necessary pieces of information helps to separate these details from the main content of the document. Easier to read, these points can be skimmed quickly.
- Strong headings – Depending on the content and the audience, include headings that flow alongside the thought process of the document. Think about how the reader will move from one piece of information to another in order to ensure you have included all of the information necessary for the proper outcome. When a reader subsequently returns to the documentation, these headings can provide road maps for the reader to get directly to the needed information.
- Image descriptions – When images are included, a short description of the image, such as might be included in a caption, allows the reader to understand the relevance of the picture.
- Boldfaced terms – At times, making some words boldface can help to highlight important terms, stress important tasks and draw attention to certain sections of a document.
- Outcome expectations – Where appropriate, it can be useful to include a section about what readers can expect from the process outlined in the document, a technique frequently used in training materials. With this before them, uses can compare their results to what was expected.
Structure is not a Substitute for Content
At the same time, relying on these sorts of format changes will not help to boost the effectiveness of a poorly written document. Instead, structure strategy should be used to call attention to information and improve its usability rather than to distract from a lack of details.
Structure provides a backbone for a technical writing document, allowing for improved usefulness of the document. Developing and applying a consistent structure strategy can be an especially important step in improving documentation.
Related topic:
Structure and Technical Writing, Part 1
No matter what a technical writing piece may be trying to convey, structure matters.
Not only will structure allow the reader to effectively skim the piece for needed information, but providing a consistent structure, such as including the same sections in each article or user guide allows for congruency among documents. With increased congruency comes increased usability and that’s the goal, isn’t it?
(more…)
For many people, the concept of technical writing doesn’t seem to bring up arguments about language. After all, the precision needed in technical writing seems to indicate that there are fewer arguments about grammar and word usage than in other forms of writing. But is this the case? Within the area of technical writing, standards seem to be necessary, but they also seem overly rigid in some writing situations.
A mouthful, to be sure.
(more…)
Technical writers and trainers aren’t always in an office or at a desk. When technical documentation or training materials need to be updated, the person responsible may be on the road at a customer site, snowed in or otherwise not in reach of the office desktop. While having laptops, netbooks, or tablets and access to the Internet is a good start, how can multiple users access the same file from different locations?
Cloud computing offers new answers to these problems for many professions.
(more…)
According to many experts in technical writing and communications, 2011 is a time of change.
The predictions for technical communication in 2011 include issues such as:
- A gap in technical writing and modern technical communication
- Accountability
- A focus on business value
- Authoring tool value
What does all this mean for the coming year?
(more…)
Editor’s Note: This was the feature article in this month’s TechCom Manager newsletter, reprinted here with permission. Click the previous link to subscribe to the newsletter.
Buckley Jeppson
On October 13, 2010, President Obama signed into law the Plain Writing Act of 2010, a law that aims to make federal government writing clearer. This article summarizes the new law, briefly explains the nature of Plain Language writing, and outlines the implications for technical communicators.
Efforts to implement Plain Language into government writing started back in the Clinton Administration and were heavily evangelized by then-Vice President Al Gore, but this is the first time legislation has mandated a change in the way government communicates with the public.
(more…)
In the NY Times blogs, a reader wrote about the idea of the oil spill as a case study in technical writing.
Fascinating to read, this blog brings up a number of ideas related to technical writing that deserve a closer look.
Ease of Understanding for the Target Audience
When writing a technical document, it’s essential the document be constructed in a manner that relates the information in an effective way. If the document is too complicated, readers will not be able to use it, unless they have the proper background. If a document is too simple, then the reader may miss details that can inform later decisions. Identifying the audience that will use the document will help to create a strong starting point from which to construct a technical writing document.
Impact on Users
Though the technical writing may not be as life changing as the oil spill, writing for an audience means that the audience will be impacted by the content. Keeping the impact of the content in mind allows the technical writer the opportunity to look at the information and relay those parts of the process that might have impact later, if they do not already. Better said, when a technical writer keeps in mind the outcome of the process they are describing, they will ensure all of the details are included that might affect the way the outcome looks.
Overall Presentation
The chart the class used in order to look into the oil spill as a case study is simple and clean. This allows a person to easily review the overall picture before looking at the more minute details. With this sort of presentation, a person doesn’t feel overwhelmed by too many details up front, and are far less likely to skip over important details presented later on.
Creating a clean document is especially essential when it’s also clear that the impact will be great if the instructions aren’t followed precisely or the information isn’t easy to understand.
With more mobile devices than ever before, your technical writing team may not be able to avoid them anymore. From iPads to iPhones, notebooks to netbooks, the mobile device is ready to take over the technology market.
What does this mean for you? It means that you’re going to see documentation accessed from more platforms than ever before. Is it time to start hiring technical writers who can also create apps and compatible programs?
The Case for More Training
Since many more employees are using mobile devices to access their workstations, the technical writing team will need to have more training in how to create manuals and training supplies which will be readable across these platforms.
(more…)
