570 likes | 763 Views
Why the Documentation Sucks and 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. Sysadmin Aptitude Test.
E N D
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
Sysadmin Aptitude Test • User:System Administrator:: System Administrator: • (a) Marketing department • (b) Pointy-haired boss • (c) Technical writer • (d) Loki, creator of discord
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
Topics • Myths of technical writing • Inherent difficulties of technical writing • Typical projects and associated issues • Improving administration documentation
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
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
Topics • Myths of technical writing • Inherent difficulties of technical writing • Typical projects and associated issues • Improving administration documentation
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
Topics • Myths of technical writing • Inherent difficulties of technical writing • Typical projects and associated issues • Improving administration documentation
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