Software User Documentation: A How To Guide for Project Staff (Software Engineering Project Management) - Softcover

Tuffley, Dr David

Softcover

ISBN 10: 1461133378 ISBN 13: 9781461133377

Publisher: CreateSpace Independent Publishing Platform, 2011

Synopsis

Every software project eventually arrives at the same uncomfortable moment: the product is built, the deadline is looming, and someone looks up from their keyboard and says, "Oh — we'll need a manual." What follows is usually a disaster. A programmer's technical notes get processed through a word processor, repackaged with a title page, and handed to users who flip through it once, set it on a shelf, and never touch it again. The software fails not because it doesn't work, but because nobody can figure out how to use it.

Software User Documentation is the guide that prevents that outcome.

Written by Dr David Tuffley — senior lecturer in sociotechnical studies at Griffith University and a technical writer with decades of experience in both the Australian public service and the private sector — this compact, authoritative manual covers the entire documentation lifecycle from initial planning through to post-publication maintenance. It is grounded in IEEE Standard 1063, the internationally recognised benchmark for software user documentation, and it delivers that standard's wisdom in precisely the kind of clear, accessible prose it advocates.

The book opens with a bracing diagnosis: the computer industry has a documentation problem, and users are the ones who pay for it. The gap between a programmer's internal world and the everyday user's experience is not a technical problem — it is a communication problem. Bridging that gap requires a specific discipline, a specific method, and a specific set of skills. This book provides all three.

From the earliest chapters on preparation — how to gather source material, construct a documentation project plan, estimate time and resources, and profile your audience — to the nuanced craft of clear writing (active voice, present tense, short words over long ones, no tired clichés), the guide moves methodically through every stage of the process. Readers learn what makes first drafts work, how to structure a document so that users can find what they need without frustration, and how to handle error messages, appendixes, glossaries, and indexes in ways that serve rather than confuse.

There is practical wisdom here that textbooks rarely touch: how to survive writer's block, how to set up an ergonomic workspace, when to print a draft rather than edit on screen. The chapters on editing and proof-reading are meticulous without being pedantic, and the guidance on reviewing and field-testing manuals — who should do it, how to brief them, how to act on their feedback — reflects the hard-won experience of someone who has managed real documentation projects under real deadline pressure.

The final sections address online help systems, production and binding, version control, and the often-neglected art of document maintenance after publication. A comprehensive glossary of computer terms and a set of ready-to-use project forms round out the package.

What distinguishes this book from the narrow technical writing manuals that crowd the shelf is its insistence that good documentation is, at its heart, an act of translation — from the world of the machine into the world of the person sitting in front of it. Get that translation right, and users succeed. Get it wrong, and even brilliant software becomes shelfware.

If you write, commission, review, or manage software documentation — or if you simply want users to actually use what you build — this book belongs on your desk, not your shelf.

About this title

About the Author

David Tuffley PhD is lecturer and researcher at Griffith University in Australia. David is a Software Engineer, though his interests range across Comparative Religion, Philosophy, Psychology, Anthropology, Literature, History, Design and Architecture. David has been an academic since 1999. For 15 years before academia David was a technical writer and later a consultant for public and private sector IT clients in Australia and the United Kingdom. He combines theory and practice in a focussed and disciplined way that has proved effective for solving problems for clients.

Edition details

• Publisher: CreateSpace Independent Publishing Platform
• Publication date: 2011
• Language: English
• ISBN 10: 1461133378
• ISBN 13: 9781461133377
• Binding: Paperback
• Number of pages: 153