Technical Writing, a form of technical communication, is a style of formal writing and business communication, used in fields as diverse as computer hardware and software, chemistry, the aerospace industry, robotics, finance, consumer electronics, and biotechnology. Good technical writing clarifies technical jargon; that is, it presents useful information that is clear and easy to understand for the intended audience.
With our economy still on the down slope, it is difficult for technical managers to justify keeping an excessive amount of technical writers on their staffs, let alone hiring new ones. In many cases, managers feel they don’t even need writers, arguing that everyone has writing ability. Of course, today’s technical writers not only write, they also perform many other tasks: programming, web development, training, and so on. Add to that the fact that many are also highly trained and certified in other areas besides writing.
In a time when corporate downsizing is the norm rather than the exception, technical writers must constantly increase and market their skill sets to make themselves more valuable to employers. Based on our experiences as technical writers in a small company, we will define why and how to market yourself:
When you first ventured into the tech writing ranks, marketing the department was likely the furthest thing from your mind. You already had work to do, so marketing was somebody else's job.
There are many preparatory steps in technical writing that you as a writer need to take before actually sitting down and start writing a technical document. Here are 7 issues you need to consider in the pre-production phase of your documentation project.
Using the structured features requires advanced training and you probably won’t need them anyways unless you’re doing any “single sourcing” (which is the topic of yet another article). For example if you were doing any XML-based authoring or “database publishing” then you would definitely need to learn how to use the FrameMaker’s structured interface. However, there is an easy way to imitate structured documentation while you are still in the unstructured mode. This is one case in which you can have your cake (unstructured FM) and take a bite out of it too (by enjoying one selected feature of structured documentation).
Bulleted lists are important in technical writing. They summarize information in a manner that is easy to read and absorb. Use them whenever you can to get your information across quickly. Bullets are ideal for things-to-do, equipment, sets, collections, cooking ingredients, and all kinds of other lists.
You put forth your best effort to explain to the stupid sods exactly how and where they screwed up, then they have the temerity to not appreciate your fine efforts. Here's how to write a report that will cause change, instead of uproar.
This presentation describes the standard structure of a lab report and provides a methodology for successfully producing such a report. It includes a description of the generic structure of a report and variations on this theme.
A white paper in the high-tech industry is a technical document that describes how a technology or product solves a particular problem. It's a marketing document and a technical document, yet it doesn't go too far in either direction. A good white paper is informative and is designed to show off the advantages of a product or technology.
A well-designed user guide contains a copyright page, which provides copyright information for your company's products as well as for any third-party products mentioned in your document.
Perhaps our headings should focus a bit more on user benefits? For example, "Overview of batch printing - Save time and improve document organization" is a bit more engaging, especially if your customer is struggling with those issues.
In the continuing absence of maturity in the software world, it’s the documentation that has to treat the tool-user with respect. Which is a further argument against Knuth’s Literate Programming. Since it’s all too common to see software toolmakers treat tool-users with short shrift, it’s a useful caution to have the ’software is written in one corner and documented in another’.
Keeping to the four rules articulated here—and never forgetting the axiom—will definitely improve your documentation. If nothing else, recognizing and observing these rules will raise the status of documentation and the people producing it. And they’ll use that raised status in at least two ways.
By becoming more technical, you can interact more efficiently with software developers and qualify for a greater variety of software documentation projects. This paper outlines ways to learn more about three prevalent technologies: programming languages, databases, and Web server technologies.
This case study reviews a hybrid face-to-face (F2F) and virtual collaboration between the State of Hawaii’s Division of Forestry and Wildlife and a team of university technical writing students to indicate specific features of the hybridity as it shaped the collaboration. In a course focused on organizational authorship, students were tasked with learning about the organization’s workplace culture to successfully represent its ethos in a report on the history of forestry in Hawai‘i. Moments and modes of collaboration are discussed chronologically as they enabled successful report writing, featuring key components: clearly stipulating terms of collaboration through service-learning, assessing fit between the course and the organization, emphasizing the need for onsite visits by students to ascertain the workplace culture, conducting swift follow-up on challenges in meshing the virtual with the face-to-face, and leveraging each mode of collaboration synergistically rather than discretely.
Hypertext is a novel approach to computer-based information management based on associative indexing. The concept in general and the characteristics of typical systems are briefly reviewed. Strategies for applying hypertext techniques to the process of writing a technical document are examined. The way in which hypertext documents are used is discussed, focusing on a commonly encountered problem -- user disorientation within the document. Hypertext-based technical documents are compared and contrasted against their paper-based antecedents.
These are just a few ways in which we can reduce your time spent thinking about the documentation and get you back to your task at hand. Unfortunately our ability to excel at these tasks are limited by two rather large factors:
I’m not sure what you can do to help users continue to increase their knowledge of an application. The problem is that even if you provide the means for advanced learning, whether through tips, newsletters, blogs, or interface notes; users already familiar in performing a core set of tasks are inclined to remain in their comfort zone.
Technical Writers (aka Technical Authors, Content Wranglers and Documentation Managers) have an unfair image. This project aims to challenge this image, by showing technical writers in a different light. The photos below are of technical communications professionals, doing a variety of activities.