Barriers and Approaches to Reviewing Documentation

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.

Boston Broadside (1997). Articles>Documentation>Editing>Collaboration

Bilingual Team Writing: How One Company Is Meeting the Demands of Simultaneous Software and Documentation Release in Multiple Languages  

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.

Duffy, Gerald J. STC Proceedings (1994). Articles>Documentation>Localization>Collaboration

Customer Partnering: Data Gathering for Complex Online Documentation  

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.

Hackos, JoAnn T., Molly Hammar and Arthur Elser. ComTech Services (1997). Articles>Documentation>User Centered Design>Collaboration

Documents That No Project Cannot Be Without

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.

Dick, David J. Carolina Communique (2008). Articles>Documentation>Project Management>Collaboration

Extreme Programming

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.

Software Reality (2005). Articles>Collaboration>Agile>Extreme Documentation

Harnessing the Earthquake: Reaching Group Consensus When Changing the Documentation Process  

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.

Coppola, Carolyn M. and Kristine Logan. STC Proceedings (1994). Articles>Documentation>Collaboration

How to Convince Others of the Importance of Documentation

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?

HelpScribe (2008). Articles>Documentation>Collaboration

The Issue of Quality in Professional Documentation: How Can Academia Make More of a Difference?      

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.”

Spilka, Rachel. Technical Communication Quarterly (2000). Articles>Documentation>Collaboration>Technical Writing

Listening: the Often Forgotten Ingredient

If listening isn't in the mix when developing documentation, then the project may not cook.

Allen, Clare. Boston Broadside (1992). Articles>Documentation>Collaboration>SMEs

Managing a Documentation Project from Both Sides of the Atlantic  

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.

Morgan, Sharon. STC Proceedings (1998). Articles>Documentation>Collaboration>Online

Notes on the Documentation Development Process

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.

Hart, Geoffrey J.S. Geoff-Hart.com (1996). Articles>Documentation>Collaboration

SIGDOC Reminiscences    

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.

Rigo, Joe. Journal of Computer Documentation (2001). Articles>Documentation>Collaboration>History

SMEs in a Nutshell  

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).

Docsymmetry (2003). Articles>Documentation>Collaboration>SMEs

Software Documentation Process - McGraw-Hill School Systems  

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.

Rogers, Anne E. STC Proceedings (1996). Articles>Documentation>Workflow>Collaboration

Strategies for Winning Recognition: Building a Visible, Viable, and Valuable Documentation Team  

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.

Harkness, Holly E. STC Proceedings (2003). Articles>Documentation>Collaboration>Technical Writing

The Team Approach to Writing Policies and Procedures  

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.

Whitmer, Diane L. STC Proceedings (1996). Articles>Documentation>Technical Writing>Collaboration

Team Meets Dream: Successful Online Documentation  

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.

Piacenza, Alexandra and Sandra Pirghaibi. STC Proceedings (1998). Articles>Documentation>Collaboration

Teamwork and the Product Documentation Process

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.

Hart, Geoffrey J.S. Geoff-Hart.com (1997). Articles>Documentation>Project Management>Collaboration

Two Time Zones Beat as One: A Model for International Project Management  

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.

Auten, Kathlyn, Joan L. Kellogg and Sudha Seshadri. STC Proceedings (1994). Articles>Documentation>Collaboration>Online

What Kind of Teamwork Improves Usability?

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?

Edwards, Kirstie. Usability Professionals Association (2005). Articles>Documentation>Collaboration>Usability

Wikis for Supporting Distributed Collaborative Writing  

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.

Wei, Carolyn, Brandon Maust, Jennifer Barrick, Elisabeth Cuddihy and Jan H. Spyridakis. STC (2005). Articles>Documentation>Collaboration>Wikis

Working Together: Developing a Joint Documentation Project in Two Countries  

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.

King, Nancy. STC Proceedings (1993). Articles>Documentation>Collaboration>International