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.
First, I present some of the reasons why lone authors often feel stuck. Then I examine several ways how authors can find the time to work on improving their situation. In the last part, I present some best practices that show how lone authors can manage their work to make it more beneficial for their organisation and their own career.
In today’s ROI world everything is measured, and what is measured then becomes a performance report, often, nearly always, will determine bonuses, promotions and compensation. So it’s more important than ever to establish a formal system for managing communications requests and tasks. Forget about the bonus, it’s your and your staff’s sanity we’re talking about here.
Good web design does not necessarily mean good use of colors and layouts, but it does transcend beyond it. Design elements like color, font, size, frame, etc. play an important role nonetheless, but what is more important is that how it affects the aesthetic sensibilities of the users. The warmth and the feel of the web site, or in another words, the texture of the web site is a crucial area to turn our attention to. By texture of the web site what it means is the subtleties of the surface of the web site. Varied aspects as discussed in this article, when sensibly used -- and in combination with good deign skills aimed at creating intuitive appeal -- are of definite help of when it comes to developing engaging graphics on your web site.
The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?
I was surprised and mildly pleased this weekend to see my sister-in-law Karin give a quick reference guide or “cheat sheet,” as she called it, to her grandma for her birthday. The guide focused on accessing and sending email in Gmail. Grandma was grateful and elated to see the work and detail that went into the guide, which was laminated and narrow enough to prop up next to her [ancient] computer.
We as technical communicators ought to afford each other the courtesy of using each other’s materials when the need arises. As the writers, we know how valuable it can be, and if we don’t use it when the need arises, we’re contributing to the prevalent concept that “no one reads it anyway.” By doing so, we shoot our own profession in the foot.
A glossary is an alphabetically arranged list of terms, with a definition or an explanation of each term. A term can be a single word or many words. Typically, in a printed document, the glossary is at the end of the document. Usually, in online help, each term in a topic, or the first instance of a term, has a popup that explains the term.
The GNOME Documentation Project (GDP) aims to provide GNOME and GNOME applications with a complete, intuitive, and clear documentation system. At the center of the GDP is Yelp, which presents a unified interface to GNOME-specific documentation as well as other Linux documentation such as man pages and texinfo documents. The GNOME Help System provides a comprehensive view of documentation on a machine by dynamically assembling the documentation of GNOME applications and components which are installed.
Aaron and I advocate minimalism in documentation. Our definition of minimalism differs slightly from how some people may define the term, and we take some heat for it. But no matter how you define it, the aim of minimalist doucmentation is always the same. To give user the information they need in the most concise, readable, and accessible way.
Writers can increase the value of their documentation by visiting customers where the customers work and seeing what they are doing. It's easier to write targeted topics when you know what readers need. Ann Beebe, User Education manager for Visual Studio, gave me two examples of writers who went into the field and discovered how the customer's experience can be very different from the experience in the development team.
I’m enough of a perfectionist that I mentally wince every time I find myself thinking, “It’s good enough.” It sounds like a cop-out. It sounds like avoidance of responsibility and ownership. It sounds like I’m indifferent.
Help content gets no respect. For one thing, it is content, and our horse-before-cart industry is only now beginning to seriously tackle content strategy. For another, we assume that our site is so usable, nobody will ever need the help content anyway. Typically, no one is in charge of the help content and no strategy exists to keep it up to date. On most sites, help content is hard to find, poorly written, blames the user, and turns a mildly frustrating experience into a lousy one. It's time to rethink how we approach this part of our site. Done well, help content offers tremendous potential to earn customer loyalty. By learning to plan for and create useful help content, we can turn frustrated users into our company's biggest fans.
In late July 2009, I was accepted into the program. The class of 12 students began on a Saturday in late August with a day-long orientation facilitated by STC Member Greg Eller. We heard from several other technical writers sharing their experiences and job opportunities in the field.
Don't you think that it is a tragedy that 95 percent of the people who desire to be technical writers have a poor command over the language? I am sure all of us make a mistake or two, once in a while. But to make it in every sentence and paragraph shows utter disrespect for readers.
If you wish to start an undergraduate professional and technical writing program at a small liberal arts college, you will find good arguments for your project in the educational writings of Sir Francis Bacon. Unlike other Renaissance Humanists, Bacon located the New Learning (what we now call the humanities) within the related contexts of scientific discovery and invention and professional training and development. His treatise, The Advancement of Learning, proposes to draw knowledge from and apply knowledge to the natural and social world. Bacon's curricular ideas can benefit emerging PTW programs in the humanities in three ways: They make a convincing apologia for most English departments and writing programs, wed humanistic education to public service, and provide a rich but practical theoretical framework for program development and administration.
Perhaps Giambattista Vico was only half right when he proposed his cyclical theory of history. Besides returning to the same key ideas, civilizations tend to suffer from the same nagging headaches. This is equally true, on a smaller scale, of academic disciplines. They are defined less by their innovations than by their recurring problems and dilemmas. This paradox certainly applies to professional and technical writing. At the dawn of the new millennium, our discipline faces the same vexing questions it confronted fifty years ago: Are we primarily practitioners and consultants or scholars and teachers? Do we train or educate students? Should we situate our practice in the classroom or the workplace? Is our subject closer to rhetoric and communications or the natural and social sciences?
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.
In 1999 the member societies of INTECOM recognized there was a need to help technical writers in all countries who have to write English-language technical documentation for products that will be sold worldwide. If they are writing for an audience solely in the UK, the Scandinavian countries, Australia, New Zealand, and South Africa, then British style is appropriate. Similarly, if they are writing for an audience solely in North and South America, the Philippines, and many Asian countries, then US style is appropriate. But if they have to write a single set of documentation for use in all countries, then a difficult decision has to be made.
Lists wacky, bizarre, surreal and otherwise strange examples of technical documentation, particularly illustration. Has not been updated for a number of years.
As with previous editions, the editors have done a marvelous job. This is the type of book that every writer should have. As I stated before, it is not a how-to-write book, but more of a 'tools for writing' book. I find myself referring to it often when I'm thinking of how to pronounce a specific word or how to go about putting together a proposal, abstract or white paper, or even how to interview an engineer or programmer for information about a product I'm documenting.