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.
The way I learned to write documentation was that you started work on a new project by spending a decent amount of time getting to know your subject matter. I don't mean getting to know the software, I mean getting an understanding of the environment in which the software will be used and the reason for its existence - that is: what's the real value of the software to its users and what do they want to achieve by using it?
Scott Adams created a character named Tina the tech writer for his comic strip Dilbert. She’s brittle, humorless, literal, and wonders why she doesn’t get any respect or interesting work. Like many caricatures, Tina has a basis in reality. This blog will explore issues in technical communication and its professional association the Society for Technical Communication.
I’m working on a little style guide for direct and concise technical writing. One pointer is to avoid the use of should or shouldn’t when what you really mean is do or don’t. Saying something like “shouldn’t” makes it sound optional. In other words, shouldn’t leaves a little room for doubt. Don’t, well, doesn’t.
Your product's unexplained features can turn into costly flaws. This article describes three real-world products with just such "features." It presents ways you can prevent these feature-to-flaw conversions by improving the User Documentation for your products.
Your product’s unexplained features can turn into costly flaws. This article describes three real-world products with just such “features.” It presents ways you can prevent these feature-to-flaw conversions by improving the User Documentation for your products.
Sure, the economy's booming now, but as the Asian crisis becomes the North American crisis, it pays to remember Newton's famous law of gravity: what goes up must come down again. And, of course, when the economy comes down and pension fund managers start asking those awkward questions about why they should remain invested in your company's stock, managers have a lemming-like tendency to trim staff to make room for short-term profits and long-term plausible deniability. As a technical communicator, you're obviously well up on the hit list, which some might see as a bad thing--but there's a silver lining to every cloud (or, in our case, a copper lining; they don't pay us well enough for silver). In fact, the good news is that it's easy to ensure you're the first one fired, so you can leave before the job becomes mundane without looking like a quitter. Then there are all those perquisites (severance pay, a little downtime)...
The article outlines the technical writing tutorial (TWT) that preceded an advanced ESL writing course for students of English Philology at the Jagiellonian University. Having assessed the English skills of those students at the end of the semester, we found a statistically significant increase in the performance of the students who had taken the TWT in comparison to the control group who spent the time of TWT doing more traditional exercises. This result indicates that technical writing books and journals should be considered as an important source of information for teachers of writing to ESL students.
By partly adopting the process suggested by Daniel Brolund we, the technical writing team, can be involved right up front and the documentation can be one of the methods used to validate the software as it is being built.
Technical writing education in the community college is complicated by the need to serve multiple populations, including traditional college students, vocational/certificate students, and community businesses. At Heartland Community College (HCC), the Corporate Education Department serves the needs of businesses by providing workshops of varying lengths and content areas. At the same time, the Writing Program and the English Department serve the needs of traditional and vocational students through writing courses in composition, technical writing, and business writing. Since each department espouses different philosophies and is addressing the needs of a different audience, technical writing instruction varies across the College. Rarely does one course design affect the other, yet I believe that conversations between departments could help the College resolve some of the contradictions that accompany its dual mission.
In reality, the user just wants a brief, clear explanation of a concept or task. The user will glance and skim — reading behaviors hardly worthy of the elitist grammarian who argues the finer points of “which” versus “that” in restrictive clauses.
Lead writing is a process that moves the information development cycle into the product development cycle. Writers and programmers work together from the beginning to produce both code design and supporting information. This process ensures that information developers can actively participate in design, and programmers can contribute to supporting documentation. Both groups gain an appreciation for each other's perspective, expertise, and skills, producing a more customer-oriented product.
L'ecriture technique est une limite qui represente un ensemble d'activites de plus en plus large qui sont concues pour communiquer l'information comprehensible qui peut aident a peuple soit productive. Le contenu cree par les auteurs techniques a traditionnellement implique des articles comme 'comment-' aux manuels, aux guides de reference et aux rapports de corporation. L'apparition de nouvelles technologies, de tendances et de coutumes nous incite a augmenter l'armature de la reference qui entoure les activites d'un auteur technique.
Much has been said about the creation of modular documentation - from content management systems, to information architecture, to delivery forms, to the usability of modular content (content being easier to use, easier to understand, and easier to find), and so on. However, not much has been said about the editing of that content, and what the editor's role is in such an environment.
Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like 'well, if the user can't figure that out, maybe he’s in the wrong job!'
Lately, when I’m writing for training, I’m thinking of actually having a conversation, of talking to a real person. When I write other documents, for some reason I’m not thinking this way. It’s a problem because my user assistance content probably comes out dry as a desert in summer. In addition to not being as conscious of users as I should, perhaps there are a couple of organizational factors affecting my mindset.
The tools and techniques utilized in the technical communications profession are constantly improving and changing. Information Technology (IT) organizations devote the necessary resources to equip and train engineering, marketing, and sales teams, but often fail to do so for technical documentation teams. Many IT organizations tend to view documentation as an afterthought; however, consumers of IT products frequently base their purchasing decisions on the end user documentation's content, layout, and presentation. Documentation teams play a unique role in IT organizations as they help to build and create a public identity through end user manuals and the corporate website, as well as maintain intellectual knowledge through knowledge sharing and management. The technical communicator 'makes sense' of complex engineering specifications by creating user-friendly manuals for the layman. The practitioner who compiles and records this complex information is a valuable resource to any IT organization. Therefore, on-going training for technical documentation teams is essential to stay competitive in the fast-paced technical market. Technical communicators in IT organizations who only write end user manuals are becoming a rarity. Research indicates a marked trend toward technical writers in multiple roles and varied responsibilities that include web design and development, and business systems analysis functions. Although these added roles and responsibilities require training on some of the newer software tools and more complex programming tools, technical communicators are experiencing difficulty keeping pace with these tools. This article discusses technical documentation teams in IT organizations and provides an on-going training assessment to help technical documentation managers identify their team's strengths and weaknesses. In addition, measures and results from a study conducted at eight IT organizations, are provided to show the effect of how the integration of on-going training for documentation teams enhances individual competency and improves team performance.
A basic prerequisite for good content strategy is that the content should be of good quality—accurate, concise, and complete. An efficient workflow with professional technical communicators creating high-value information is typically the least expensive option (better, faster, and cheaper).
Procedures are the meat and potatoes of technical writing. They help users get the job done. Follow these tips for writing clear and useful procedures that your users will appreciate.
When technical communicators are part of a development team, we can do much more than write manuals. Our analysis and communications skills, user perspective can help launch a project team into productivity. We have a unique skill set which enhances the productivity and quality of the development process. By involving us early, we can assume technical communications tasks that developers otherwise perform. This exposure gives us a broader and deeper understanding of that which we communicate. Our involvement means better communication; with users and team members, and in deliverables and development processes.
I wish Flare gave me an option before creating the printed documentation: embedded or linked images. I went through a lot of rigmarole before finally figuring out how to get the images embedded so I could share the document.