http://tc.eserver.org/dir/Articles/Documentation/Collaboration A listing of the most recently indexed works about Articles and Documentation and Collaboration in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Articles/Documentation/Collaboration http://tc.eserver.org/35421.html http://tc.eserver.org/35421.html It's a simple fact of life. Developing products in today's world requires shorter cycles, sensitivity to customer needs, and a focus on deliverables that breaks the old waterfall development paradigm. More and more there is a need for teams to focus on the entire development process and deliver precisely what customers need with little or no fluff. As products move towards the user-centric model of product development the push is for more intuitive interfaces with little need for documentation -- or does it really? http://tc.eserver.org/35192.html http://tc.eserver.org/35192.html The idea of a Book Sprint is that you can get lots of documentation written in a focused amount of time with the right team and some amount of content already in place. Gathering people in the same room when possible is extremely helpful and motivating as well. http://tc.eserver.org/35080.html http://tc.eserver.org/35080.html Project teams may recognize that reviews are not working well, though the may not understand why. A valuable solution is to conduct ”lessons learned” analysis following the end of the project. Too often, though, post-writing-project analysis receives little commitment or meaningful effort, but why? http://tc.eserver.org/34696.html http://tc.eserver.org/34696.html Beyond the obvious impact on the Social Web, Google Wave is also going to change aspects of every business that currently relies on communication and collaboration tools of any sort, including the ubiquitous but lowly email. http://tc.eserver.org/33419.html http://tc.eserver.org/33419.html One of the things that makes quality documentation on a product is a review process. I think many technical communicators would agree with me, however, that sometimes the process becomes more cumbersome than beneficial. The more people involved, the harder it is to meet deadlines. http://tc.eserver.org/32161.html http://tc.eserver.org/32161.html 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. http://tc.eserver.org/31035.html http://tc.eserver.org/31035.html Short deadlines force project teams to quickly design, test, and release the product with little or no design documentation. If these documents are written, they generally are not well-written and are not comprehensive. The fact of the matter is that most project teams do not have enough staff to design the product, let alone write and manage documentation. This situation creates an ideal opportunity for technical writers to assist the project team in more ways than writing a user guide. http://tc.eserver.org/30808.html http://tc.eserver.org/30808.html If you've been a technical writer for long, chances are you've had to convince someone of the importance of documentation. It just comes with the territory. People often don't see the value of writing technical manuals. So how do you convince them? http://tc.eserver.org/30621.html http://tc.eserver.org/30621.html As companies become more internationally orientated, joint projects among groups in different countries are becoming more common. These projects offer unique opportunities, including learning about another culture and the chance to travel. They also present obstacles, including difficulties in communication. Time differences allow a small window for phone calls. Periodic face-to-face meetings are essential, since they build under- standing and tolerance that carry over into communication by phone or electronic mail. Cultural and national differences in business practice further complicate the picture. It is important to work out all procedures, standards, and objectives in writing for the project to succeed. http://tc.eserver.org/30347.html http://tc.eserver.org/30347.html This article discusses some important issues in implementing a software documentation review process. If you are part of a small development organization and have few reviewer resources available, you may have to improvise techniques for providing the services and procedures suggested here. http://tc.eserver.org/30326.html http://tc.eserver.org/30326.html If listening isn't in the mix when developing documentation, then the project may not cook. http://tc.eserver.org/30139.html http://tc.eserver.org/30139.html Most of us struggle every day with keeping the lines of communication open between developers, subject matter experts (SMEs), customers, and writers. Sometimes you can circumvent these difficulties by simply walking upstairs or across the hall and chatting with the appropriate person. But what happens when it's not a staircase or hallway separating you but a very large ocean? The best way to keep an overseas project on track is to put together a writing team in the most convenient location; meet at least once with the development team; and set up your communication channels early. http://tc.eserver.org/29414.html http://tc.eserver.org/29414.html Define your audience, and their needs, explicitly and carefully. The definition process may lead you to include additional material such as indexes, system requirements, and contextual notes (e.g., lists of exceptions), as well as the preplanned documentation. http://tc.eserver.org/29415.html http://tc.eserver.org/29415.html Get to know your new teammates. Get to know your audience. Define the product's features. Create a mockup of the user interface. Begin to document the features and interface. http://tc.eserver.org/28320.html http://tc.eserver.org/28320.html Wikis allow distributed teams to collaboratively write and edit documents through the Internet in a shared online workspace, without the need for special HTML knowledge or tools. The flexibility of wiki technology is a boon for increased cooperative work on large team projects. However, wiki technology also complicates notions of usable design as the information architecture of a wiki site may be created on the fly by all participants rather than by a dedicated technical communicator. This paper describes the basic technology of wikis, some advantages and disadvantages, and areas of concern with regard to information design. http://tc.eserver.org/27586.html http://tc.eserver.org/27586.html Extreme Programming (or XP) is a popular software development process that encourages a return to the days of little or no documentation, Design After First Testing, and Constant Refactoring After Programming. Despite its popularity, not everyone thinks XP is a good idea. http://tc.eserver.org/25904.html http://tc.eserver.org/25904.html Professionals are increasingly working in networked teams where electronic media and asynchronous communication play an important role. So how can communication behaviours in these contexts predict usability? Do efficiency, effectiveness and satisfaction in the communication process lead to the same for the resulting documentation? http://tc.eserver.org/25011.html http://tc.eserver.org/25011.html A causal-analysis session is a problem-solving method that brings groups of people together to jointly solve common problems and make process changes. This method ensures that everyone who will be affected by a process change has the opportunity to provide input and agree to the solution. In large departments, reaching group consensus is a challenge. This paper presents our department's implementation of the causal-analysis method. http://tc.eserver.org/24711.html http://tc.eserver.org/24711.html Challenges abound when a documentation team is based in two countries, works with software developers in four countries, and produces documentation for use by engineers in many countries. Differences in language usage, cultural perspectives, time zones, holiday schedules, and educational backgrounds are only a few of the difficulties to overcome. http://tc.eserver.org/24297.html http://tc.eserver.org/24297.html This paper chronicles the development of an online program that is in use and thriving today - a process which has spanned two years and two different companies. The presenters share the encouragement and pitfalls they met along the way, with emphasis on the elements they found most important in making their efforts a success. Selection of the most appropriate tools and methodologies play an important part. But just as important are team member skills, willingness of others to share their experience, high-level sponsorship, an environment that supports innovative solutions, and plain old persistence. http://tc.eserver.org/23752.html http://tc.eserver.org/23752.html 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. http://tc.eserver.org/23154.html http://tc.eserver.org/23154.html 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. http://tc.eserver.org/22905.html http://tc.eserver.org/22905.html In the mid 1970's, technical writers documented weapons of mass destruction for the military and its contractors. There were few computer-related jobs outside IBM and the other manufacturers. Corporate systems development managers did not know that people existed who were interested in such work. http://tc.eserver.org/22144.html http://tc.eserver.org/22144.html Technical communicators today must document complex applications used in complex environments. Information about users and use models is important under these conditions, especially if documentation will be presented online. Customer partnering, a method of information gathering that supplements surveys, contextual inquiries, usability testing, and interviews, provides a way of involving the users of complex applications in the design of information delivery systems. We used this method to help a client gather important information about user and use models and design a new information library for complex server computer systems. http://tc.eserver.org/21575.html http://tc.eserver.org/21575.html A company decides to release its software and documentation simultaneously in markets with different languages. For the documentation team, the traditional model of 'write and translate' does not work any longer. A bilingual writing team collaborates to produce a handbook in two languages at the same time. http://tc.eserver.org/21407.html http://tc.eserver.org/21407.html I admit that I don't know everything about subject-matter experts or SMEs (rhymes with please). But I do know that there are some things that you should avoid asking SMEs, the main ones being 'Does the user know this already?' and 'Do I need to explain this to the user?' The problem with these questions is that the SME is likely to reply 'No!' to both of them when in fact the answer is most definitely 'Yes.' SMEs tend to believe that everyone knows as much about technology as they do. Never, never, never let the SMEs tell you how to write the documentation. A SME is the subject matter expert, not the documentation expert (that's you). http://tc.eserver.org/20556.html http://tc.eserver.org/20556.html This panel presents the software documentation processes of three companies. At McGraw-Hill School Systems, the technical writers are involved in every stage of the software development life cycle. This approach ensures that writers are always in control of the information they need and that sufficient time is available for the documentation process. Our involvement allows us to produce high-quality documentation that is up-to-date with the software’s functionality. http://tc.eserver.org/13920.html http://tc.eserver.org/13920.html 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.”