1 / 57

Why the Documentation Sucks and What You Can Do About It

Delve into the myths and realities of technical writing, explore inherent difficulties, roles of writers, and ways to enhance administration documentation.

ltatum
Download Presentation

Why the Documentation Sucks and What You Can Do About It

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

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

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

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

  4. Can’t we all just get along?

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

  6. Myths of Technical Writing • The Documentation Decameron

  7. 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

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

  9. 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

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

  11. 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

  12. 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

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

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

  15. 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.

  16. 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

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

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

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

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

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

  22. 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?

  23. 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

  24. Actual example of information quest

  25. 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.

  26. 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.

  27. 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.

  28. 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.

  29. 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...

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

  31. 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

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

  33. Typical Projects and Associated Issues • It’s always something

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

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

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

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

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

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

  40. Improving the Documentation • A two-way street

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

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

  43. 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

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

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

  46. 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

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

  48. 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

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

  50. 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

More Related