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.
Technical communication must ultimately serve the reader - there must be something that the writer can do to clarify the information and make reading part of the process that makes the product usable.
Janet Swisher, who’s worked in technical communication since 1999, is an Information Developer for a medium-sized software company. Her specialist areas include online help, tutorials, API documentation and programmer guides. My “techie” cred is that she “can read code well enough to avoid asking obvious questions, and write code well enough to be dangerous.”
How does Jobs Rated determine which professions rank better than others? Data on each job is broken down into five key categories: Physical Demands, Work Environment, Income, Stress and Hiring Outlook. Technical writing comes in at the #13 top career in the U.S., by these measures.
When the Corrigo managing editor saw that I specialize in teaching engineers and scientists to write, she asked me some provocative questions, and then asked if I would turn the answers into a blog post.
The official documentation for most apps or gadgets doesn’t always pack the information users need. It covers the basics, but it doesn’t go much further. Community documentation can fill that gap, but users need to do a lot of searching. Is there a way to effectively and efficiently combine the two?
How can you make documentation more clear, consistent, and correct for your users? Following are some guidelines I find effective when documenting concepts and organizing documents.
While gathering information for a documentation project, what challenges do we have to overcome? A presentation of data based on responses to an online survey.
After releasing documentation for a calendar application, we received so many questions and frustrated feedback from users that I started thinking about publishing a page in the help describing what the calendar doesn’t do. I’m in an agile shop, so the calendar is still undergoing development, and many of the features people want are eventually coming; other features are problematic due to bugs; other features are frustrating by design.
This week is my last Agile sprint for a while, but I think I’ll adopt some Agile principles and apply them to my new work lifestyle as an advisor for LugIron and a contractor for Informatica here in Austin.
Kathy Bowrey's Law and Internet Cultures critically deconstructs the law in the context of legal culture, and especially looks at how U.S. law, practice, and culture has influenced technology law. Bowrey, a lecturer in the Faculty of Law at the University of New South Wales, writes as an "Australian author" but her analysis clearly contains a global perspective as she looks to global structures and laws in other countries such as the United States. The book's analysis draws upon an incredibly broad range of literature including but not limited to traditional "literature" (e.g., Orwell's 1984), economic analysis, communications theory, and cultural studies. She stretches her analysis, connecting the heretofore disconnected (like Foucault, Coombe, Mandeville's travels, Napster, Grokster, etc.) and makes these horizontal connections in the context of discussions of verticality--like globalization, international standards, international patent norms, and global governance. The reading will be difficult for folks without a solid background in information technologies and law (and is just plain difficult for reasons mentioned below), but Bowrey does provide at least brief definitions and description of acronyms where need be. She tends to begin chapters with details and then brings things together at chapter's end--but this strategy seems to work for the complex subject matter. This is a great book for reading out of order or skipping to particularly relevant sections. Each section of each chapter can hold together on its own. Numerous diagrams and illustrations add to the flavor of this unique and much-needed book.
We tech writers can learn from our chunks of content: What makes a topic successful can also make us writers successful! I think there’s a lesson for tech writers here beyond team management: How successful you’ll be in your work as a tech writer depends on how well you define your job’s purpose and communicate it to others.
If you asked me what the most painful part of being a technical writer is, my answer would be: 'Getting reviews on time. Getting good feedback and inputs on your work.' For me technical writing has been very pleasurable because I hardly got any review comments. My morale has therefore been very high. Project managers, developers and others are so busy trying to come up with good software (read trying to fix all the goof-ups and bugs!) that they usually tend to give documentation lesser importance. User manuals, who reads them anyway? We do not have time for it!
Although any writing, when taught correctly, will improve a student’s ability to think critically, comparatively speaking, technical writing is a 'fast track' to acquiring these skills.
It's time to turn out the lights. I've had a great run as a technical writer and consultant but it's time to leave the profession. In some ways I've long outgrown technical writing because client needs as a consultant challenged me and pushed me to become more than just a technical writer.
What, if anything, should technical communication programs teach their students about the nature of law and the production of legal discourse? When is technical writing also legal writing, and vice versa; when is legal writing (really) technical? Are there distinctions worth maintaining and dissolving here? Do lawyers' relationships to, and problems with, legal writing contexts and processes parallel in important ways technical writers' relationships to, and problems with, technical writing contexts and processes? If they do, is a conversation between the disciplines worth institutionalizing, at least experimentally, in each other's programs?
It’s often useful to look at the economic and technological pressures in other industries, to see if the trends emerging there are relevant to the technical communications/publications sector. In recent Blogs, we’ve covered the issues emerging in education, but the telecommunications industry might also provide some useful insights.
Book published by O'Reilly Media have a good flow to the information and they're well structured. One of the best features of many of those books is the introductory material. It can be a good guide, and help readers zero in on what they want to learn.
As technical editors, we love words. We love making sure that each word communicates clearly. If you hear that someone is an editor, you immediately think of grammar and syntax and word usage. But, as technical editors, the time has come (really, it came a while ago, but the saying goes, “the time has come”) for us to let go of a singular focus on the words. As technical editors, we must edit so much more than just the words—words on the paper or words on the screen, words in a PDF or words in a help file, words in a user interface or in a message. We have to look beyond the words.