A directory of resources inthe field of technical communication.


30 found. Page 1 of 2.

About this Site | Advanced Search | Localization | Site Maps

1 2  NEXT PAGE »



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   (PDF)

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


The Case of the Stolen Documentation

The non-writer who takes over the documentation can act like a bull in a China closet, copying and pasting from Word, mixing styles, not understanding the setup, basically wrecking the consistency, the bullet levels, the formatting. If you see the documentation later and find that the client has added steps without numbers, included text that breaks every rule in the style guide, won’t that be unnerving? Yes, it will make you want to jump out the window.

Johnson, Tom H. I'd Rather Be Writing (2010). Articles>Documentation>Project Management>Collaboration


Collaborative Walkthrough Video

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.

Bennett, Miranda. On Writing (2008). Articles>Documentation>Collaboration>Technical Writing


Corporate Collaborative Authoring

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.

Gentle, Anne. Just Write Click (2009). Articles>Collaboration>Agile>Documentation


Customer Partnering: Data Gathering for Complex Online Documentation   (PDF)

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


Google Wave Changes Everything You Know About Agile Collaboration and Technical Documentation

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.

Greywalker, Shannon. Greyfiti (2009). Articles>Documentation>Social Networking>Collaboration


Harnessing the Earthquake: Reaching Group Consensus When Changing the Documentation Process   (PDF)

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


Important Players in the Content Review Game

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.

Gryphon Mountain (2008). Articles>Documentation>Collaboration


The Issue of Quality in Professional Documentation: How Can Academia Make More of a Difference?   (PDF)   (peer-reviewed)   (members only)

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


Learn from Your Topics and Collaborate

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.

Weber, Kai. Kai's Tech Writing Blog (2010). Articles>Documentation>Technical Writing>Collaboration


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   (PDF)

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


Planning a Doc Sprint

A “doc sprint” is similar to a book sprint. We called ours a doc sprint because it focused on technical documentation and on developing a set of tutorials, rather than a single book. We invited a number of developers to join the technical writing team in a three-day sprint, with the aim of producing some quality tutorials on gadget and plugin development.

Maddox, Sarah. ffeathers (2010). Articles>Documentation>Collaboration>Project Management


SIGDOC Reminiscences   (peer-reviewed)   (members only)

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   (Word)

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   (PDF)

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   (PDF)

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   (PDF)

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


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



Follow us on: TwitterFacebookRSSPost about us on: TwitterFacebookDeliciousRSSStumbleUpon