'It's all in the manual.' How many times have you heard that - or said it in frustration? After all, when you are the person who wrote the manual, you know that all the answers are there. But time and again readers can't find what they need to know, or don't understand the material. Before you blame the reader, look again at how you've presented the material.
I have been pondering technical editing processes. Most notably, as I play on my iPad putting together jigsaw puzzles made from my favorite vacation photos, I have pondered whether most technical editors like putting together jigsaw puzzles.
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!'
I labeled wordiness the most obvious fault in technical writing. In retrospect, I think I was wrong. I believe the greatest fault our writing can have is vacuity, or lack of substance. We too often write words that say nothing.
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 have all the resources you need, do the very best job you can in all respects. But if your resources are tight, ask yourself whether you are writing the essential stuff at a level of quality users will notice. Also, ask whether the value of the documentation you are producing aligns with the economic pressures on your company.
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.
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!
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.
Having demonstrated the importance of acquiring a double agent for writing projects, we now want to explain the best ways to successfully indoctrinate a double agent. This paper will help you prepare for, orient, train, and become a mentor for a double agent to help make him or her an effective member of your writing team.
The peer review checklist involves completing a copy edit, completing a content edit, and then meeting with the writer to discuss your suggestions. Complete all sections of this checklist during the document’s peer review. (Someone other than the writer should complete the checklist.) Plan on spending at least one full day on the peer review, perhaps longer, depending on the size of the document.
Editing today covers far more than printed materials. In this discussion, I am assuming a technical editor may be required to deal with: printed materials (for example, books, pamphlets, quick reference cards); electronic (for example, online documentation, online help, web pages); video scripts; computer-based training materials. I am also assuming that the audience for the material being edited is not comprised of other technical people; or if it is, the editor is not the person responsible for ensuring the technical accuracy of the material.
Prescriptive grammar is useful for teaching English as a second language, but it has little value for the practicing writer. Clinging to it may provide emotional security, but only at the expense of making writing harder than it needs to be. The culture-wide devotion to it will not be changed in a moment. But conscientious writers can at least change their own habits, and make life easier for themselves.
As linguistic historians tell us, irregular verbs in English have been thinning out over the past thousand years. Some few irregular verbs (200 in American English per Bryan Garner; 68 per Elly van Gelderen) persist in our era. As reported by Baugh and Cable (in A History of the English Language), “the number of new strong formations has been negligible.” But when a new formation does arise, expect trouble.
In this article, our technical stylist, Kathy Underwood, lists and throws light on some excellent usage guides. Read this article and find out if you have the right reference books on your shelf.
The big secret in technical writing is that most of the harder documents aren't written by the technical writers at all. In fact, many "technical writers" never do any writing at all. Instead, the drafts are written by engineers or marketers. The technical writers perform editorial functions and provide publications services -- copy-editing, layout, review management, and so on.
Back when I was still working as a lab scientist, before I turned my career focus to writing, I knew I liked to write and was good at it. Once my colleagues discovered this, I started getting requests like, “Would you look over this paper for me and give me some feedback on it?” As I’ve gained more experience, I’ve learned that requests like these can be addressed a lot more successfully if you ask your client or colleague three things up front: “What is the task?” “What are the rules?” and “What is the deadline?”