Writing is a complex, cyclical task. The writing task requires more than formulating text to express ideas, it involves data gathering, managing constraints, formulating intentions, planning, and revising goals. Much of the complexity is due to the management of simultaneous activities and constraints. Management of these processes can lead to 'cognitive overload', which in turn can negatively affect the quality of the text produced. With technical writing, these same issues of task complexity are applicable.
Collaborative walkthroughs are a technique that my team used while rewriting our Help and adopting DITA. We believe that we were able to improve the user experience by improving the collaborative experience.
Mention team technical reviews to a group of tech writers and chances are good that you will either get a loud, collective groan, or the group will vie to tell the best review horror story. On the one hand, technical reviews are a vital part of our jobs because they help us to produce high quality product documents. On the other hand, technical reviews gone wrong are the bane of our existence. The good news is that we have the power to conduct consistently effective technical reviews. This article summarizes why we do reviews and what often goes wrong in reviews, and then summarizes steps to take before, during, and after technical reviews that can help you conduct effective team technical reviews. Although your process and team may differ from what’s described here, you can apply the information in part or in whole to improve your current review process.
Some years ago, I used to suffer from developer neglect, or to use a more scientific term, from a kind of information exclusion complex. You know what I’m talking about. Developers make updates to the interface, often at the last minute, and don’t let the tech writer know what changed. As a result, the help is wrong and out of date. It’s a frustrating experience from the writer’s perspective.
In an advanced technical and professional writing course, a pair of in-class exercises integrates the teaching of teamwork with other class topics of project management and observation-based research. The first exercise introduces teamwork in a positive way, by raising awareness of strategies for solving problems successfully. The second exercise follows up on the first, focusing on assessment of problem-solving teamwork. The pair of exercises is memorable and effective, showing students in an engaging, thought-provoking way that they have control and responsibility for the success of their teamwork. The materials for conducting the exercises, provided here, encourage reflection and discussion.
Want to know the secret to better quality documentation and improved software design? Will Kelly outlines how the key is an effective relationship between project managers and technical writers.
For those of us in the field of technical writing who didn't come at this from a computer science background (raise your hand if you’re an English major), we’re often introduced to unfamiliar technologies and terminology at the start of a project. It’s understandable then that we'd want to keep quiet and stay on the sidelines until we better understand what the developers are discussing. I’d like to suggest that doing so will lengthen the ramp-up time, and...
One common complaint a lot of technical writers have is that they aren’t included early enough in lifecycle of a project. The downsides are that by the time work hits your desk you don’t have a full picture of who the customer is, why they want whatever it is you are building, and how they want it provided to them. All of which directly impacts the information being created.
Larbi discusses the transition—including advantages—that many lone writers face as globalization becomes more prevalent and individual consultants transform into lone writer teams.
This article recommends strategies academics can use to contribute to an issue of great interest in industry: how best to define, measure, and achieve quality documentation. These strategies include contextualizing quality definitions, advocating the use of multiple quality measures, conducting research to identify specific heuristics for defining and measuring quality in particular workplace contexts, and partnering with industry to educate upper management about those heuristics and the benefits of promoting technical communicators to the strategic role of organizational “gatekeepers of quality.”
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!
In this video clip, Ecademy’s Thomas Power talks about how business leaders will have to switch between “institutional thinking” (closed, selective and controlling) and ”network thinking” (open, random and supportive). There’s a similar challenge for technical communicators - between traditional “closed” user documents and collaborative, conversational, “open” online user assistance.
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.
We are all going to have to collaborate like never before. Everyone should select at least one area of interest and specialize as best they can. Then we will need to start meeting and sharing information. Immediately. There are several ways to do this, I believe.
After our recent reorg, our tech writing group, now split up, has been wondering about the best way to realign ourselves in the new reporting structure, which has yet to be fully defined. Will we end up at the bottom, relegated into some lonely, forgotten corner of the org chart? Will we be grouped with the finance accountants and the secretaries? Or clumped into some other miscellaneous grouping, like a collection of odd socks?
I’m not convinced that proximity is essential to keeping up with project information. I’m not persuaded that there aren’t equally viable ways to gather the same data and interact, because if nothing else, the Internet has shown us how remotely distributed people can be closely connected with each other. The Internet has pulled us loose from our physical relationships, distancing us from those immediately around us and drawing us closer to others whom we never see or speak with.
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.
One challenge a technical writer faces in an agile environment is that the development team splits into a number of sub-teams, each working on a different feature or bundle of features. The sub-teams work in parallel. As a result, all the features simultaneously reach the stage where we can start documenting them, and that’s usually quite close to release date. This can cause major stress for the technical writer and can require overtime work to get everything done in time.
Technical writing teams can improve their standing within their organizations. The purpose of this presentation is to share our experiences at Mirant where we've achieved recognition and respect as a vital internal service to the IT department and, increasingly, to the rest of the company.
Individual students in two different sections of an undergraduate civil engineering laboratory were tasked with preparing three professional-quality laboratory reports. The teaching assistant and/or instructor used established criteria to grade the first two reports prepared by students in one section. The first two reports prepared by students in the other section were peer evaluated by assigned fellow students within the same laboratory section using identical grading criteria. The peer evaluated section had a higher class average than the teaching assistant/instructor graded section on the fist two reports. The third report prepared by students from both sections was graded by a professional educator/architect without knowledge of a student's class section. The peer evaluation students also had a higher class average on the third report, suggesting that the peer evaluation process may have positively contributed to those students' writing skills.
Although many companies claim to have working teams within their corporate structure, it may be difficult to use the same approach for writing documentation. With the demands for controlled documentation to meet quality standards, involvement in policy/procedure writing is an important factor in developing a sense of ownership and commitment to maintaining a document control system. A team approach to writing procedures may involve more time, but the results are operations consensus, improved writing skills, and a boost of professional confidence.