Why the Documentation Sucks and What You Can Do About It

Why the Documentation Sucksand What You Can Do About It Steven Levine SGI

Sysadmin Aptitude Test • User:System Administrator:: System Administrator: • (a) Marketing department • (b) Pointy-haired boss • (c) Technical writer • (d) Loki, creator of discord

Can’t we all just get along?

Topics • Myths of technical writing • Inherent difficulties of technical writing • Typical projects and associated issues • Improving administration documentation

Myths of Technical Writing • The Documentation Decameron

Myths of Technical Writing • Myth: Technical writers are editors • - Developers cannot write- Technical writers turn developer documentation into readable prose • Reality: Technical writers fill many roles • - No two projects have same requirements- Collaborative effort

Roles of a Technical Writer • Editing • Original writing • Maintaining documents • Producing online and web-based documentation

Roles of a Technical Writer • Coordinator • Coordinator of information from many different sources • Coordinator among various groups and departments within a company • Detective • Seeker of information • Gatherer of clues

Roles of a Technical Writer • Cop • Policing consistency • Legal issues • Nudger • Tester • User Advocate

Myths of Technical Writing • Myth: Technical writers are creative writers • Technical writers make documents “exciting” • Reality: Technical writers should be invisible • The better I do my job, the less you will know that I exist

Myths of Technical Writing • Myth: Technical writers work from design documents • Design documents provide a defined user interface • Reality: Design documents focus on what a product does (and on the code internals) • Design documents do not focus on how the product appears to the user

Inherent Difficulties of Writing Documentation for System Administrators • Care for some whine?

Servers get flaky while work never ceases;Projects are many and writers are few;Each business day brings new software releases,And no one has time to return their review.

Inherent Difficulties • Lack of resources • Time vs. number of projects • Fixed overhead per manual revision, continuous maintenance • Lack of resources is biggest killer of ideas

Inherent Difficulties • Conflicting perspectives • Where information comes from vs. who it is for • Developer  administrator  marketer

Inherent Difficulties • No usability testing • Wonderful when possible • Time commitment • Best hope is informal

Inherent Difficulties • Lack of testing in general • Relationship of testing and documentation • End of development cycle • Reliance on first users, both internal and external

Inherent Difficulties • Short release cycles • Software freeze vs. documentation freeze • Small code changes/huge documentation changes • Continuous piecework

Inherent Difficulties • Hardware/software distinctions • True for development • Meaningless for administrators • Meaningless for field

Inherent Difficulties • Writing from experience • Administrators desire hints on use, recovery from common errors, efficient configuration • Knowledge depends on experience • No experience on new products • Who writes documentation on old products?

Inherent Difficulties • Reliance on developers • Time Resource issue - Documenting one’s project would be a full-time job - Developer’s job is to write code • Interest • Occasional jewel; we treasure them

Actual example of information quest

A Writer’s Quest, Exhibit A • qsort Turn the disk queue sorting algorithm in the disk driver. If all is specified as the device, enable queue sorting for all disks in the system.

A Writer’s Quest, Exhibit B • qsort Turn on the disk queue sorting algorithm in the disk driver for the specified device. Specifying all as the device toggles a global flag that enables or disables queue sorting for all disks in a system for which you have turned on the disk queue sorting algorithm.

A Writer’s Quest, Exhibit C • qsort Toggles the flag in the profile for the specified device that indicates whether the disk queue sorting algorithm in the disk driver is enabled for the device. This flag is set to on by default. Specifying all as the device toggles a global flag that enables or disables queue sorting for all disks in a system for which the disk queue sorting algorithm is enabled.

A Writer’s Quest, Exhibit D • pddconf -d all qsort ---> turns global qsorting on. • pddconf -d all noqsort ---> turns global qsorting off (default system is built off). • pddconf -d 0232.2 qsort ---> turns qsorting on for THIS device (by default it is on). • pddconf -d 0232.2 noqsort ---> turns qsorting off for THIS device.

A Writer’s Quest, Exhibit E • qsort Turn on the disk queue sorting algorithm in the disk driver for the specified device; the device flag is on by default. Specifying all as the device turns on a global flag that enables queue sorting for all disks in a system for which the disk queue sorting algorithm is enabled; this global flag is off by default. See the EXAMPLES section. • noqsort Turn off the disk queue sorting algorithm in the disk driver for the specified device...

A Writers Quest, Exhibit F • Developer response: • looks good!

Inherent Difficulties • Summary • Lack of resources • Conflicting perspectives • No opportunity for testing • Short release cycles • Hardware/software distinctions • No experience on new products • Reliance on developers

Typical Projects and Associated Issues • It’s always something

Typical Projects • Man pages • Administrator guides • Procedures and examples • Online documentation • Others...

Typical Projects • Man pages • Inconsistent • Unedited • Cumbersome to work on • Require vigilance to maintain • Low-status on department reports

Typical Projects • Administrator guides • Theory vs. procedure • Recovery procedures? • Many different audiences • Controversy: internals and system parameters

Typical Projects • Procedures • What are useful procedures? • System availability • System setup • Same requirements as testing/QA

Typical Projects • Online documentation • True online vs. screen-displayed manuals • Technical support required • Notification of updates

Improving the Documentation • A two-way street

Improving the Documentation • Contacting the writer • Address in front of manual • What couldn’t you find readily? • Suggestions for improvements • User as reviewer

Improving the Documentation • Contacting the writer • Document a problem you solved • What happened? • What did you do? • Will this help others?

Improving the Documentation • Contacting the writer • Formalize informal networks • What do you advise new administrators? • Copy writer on questions to mailing lists • Include writers in system administrator community

Improving the Documentation • Contacting the writer • Libraries of examples • Your personal procedures • Administrator tricks • Quirks and kludges

Improving the Documentation • Contacting the writer • What’s in it for you? • Helping others • Helping yourself

Improving the Documentation • The village technical writer • Collaborate within company • System administrator/writer projects and websites • Consultation: editing, approaches, styles, formats, useful tips • Interdepartmental communication

Improving the Documentation • The global village technical writer • Collaborate outside of company • Suggestions and examples sent to technical writers establish relationships • Insider help

Improving the Documentation • LINUX and open source • What does documentation mean in an open source world? • - To vendors: No money in documentation • - To users: No product without documentation

Linux and Open Source • Collective administration experience • Complainers can fix things • Contribute to documentation: credited by name

Linux and Open Source • Role of writers • Writers can provide infrastructure • Consistency of format, terminology • Noting of gaps • General nudging • All the things we do now, on larger scale

Why the Documentation Sucks and What You Can Do About It