After many years of blogging, and consistent with my desire to move toward retirement, we have ended the Insights blog. Thanks to Doug Bedell for his years of blog support.

Procedure Writing for the ‘Masses’

Posted on January 9, 2012
Filed Under Communication, Technology, The Writing Life | Leave a Comment

On ffeathers, one of the technical writing blogs we visit, a question’s been raised about whether comments should be allowed on documentation pages, from, we presume, just about anyone in an organization, and maybe customers, too. Sarah Maddox, who presides over ffeathers, is a technical writer for Atlassian, an Australian software company.

So here we have another example of the web’s ability to promote an international discussion. The question of who might have access to documentation these days becomes wider than when paper, or a personal computer file, was the medium of expression. Atlassian produces its product documentation on a wikki – it happens to produce Confluence, one of the leading wikki software packages.

Thus group writing of documentation and procedures via commenting becomes a distinct possibility. And with it, not only might more complete and responsive software manuals arise, but a broader-beamed organization could come into being as well. If communication input is a prime means of organizational development, and it is, allowing a wider circle of commenters on a company’s emerging products could alter the organization’s reality. (If that scares you, read no further.)

Atlassian allows anyone to add comments on its documentation. “Even people who have not logged in to the wiki – their comments are recorded as ‘anonymous.'” Many of the people our colleague Dennis Owen works with in providing technical assistance at nuclear power plants will, no doubt, be appalled at the notion of anonymous comments on plant procedures. Nuclear, and other highly sensitive procedures, are available only on a need-to-know/authorized-to-know basis.

Yet, providing that enough familiarity exists with the subject at hand, group commenting on documentation can be a consciousness-raising exercise. A user’s point of view is more likely to be included, rather than just the developer’s.

And there’s always the possibility of heightened awareness as to how the developer is coming across. “What benefits do we, as technical writers, get from the comments people add?,” Sarah asks, “And do we suffer any pain?”

As a matter of fact, a few months ago Atlassian moved all of its developer documentation – procedures on software being developed for use with its own products – to a different wiki site. There, they’ve turned off the page comments and have replaced them with two panels at the bottom of each page, one allowing comments on a page in response to inquiries in a question box, and the other requesting detailed feedback if someone wants to provide it.

Making procedure writing as transparent and helpful as possible is, thus, a challenging job to do well, always with the end user, and sometimes security awareness, in mind. We know that. How to insure that we live it is sometimes another matter. – Doug Bedell

Dennis Owen, indeed, notes that he can imagine the day when all workers will carry an iPad-like device and follow their procedures on a screen instead of paper. In that case, it would make perfect sense to allow plant workers (but not just anyone) to comment. Those comments would not appear on the paper itself, which is to some extent a legal document that can’t have ambiguous information on it. Instead, they would be e-mailed directly to the procedure’s author and added to a tracking database, and he or she would be responsible for addressing them. That would be a nice, seamless way to encourage procedure comments and user-to-author dialogue.

Many procedures have sign-off steps, so after a job some paper procedures must be retrieved and digitized to become part of a plant’s record. Electronic procedures would capture all those signatures in real time and would save even more time and money.

Comments

Leave a Comment

If you would like to make a comment, please fill out the form below.

Name (required)

Email (required)

Website

Comments

Email Subscribe

Recently


Categories


Archives


Blogroll