Why the Documentation Sucks and What You Can

Why the Documentation Sucks and What You Can Do About It Steven Levine SGI 12/16/2021 1

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

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

Can’t we all just get along? 12/16/2021 4

Topics • Myths of technical writing • Inherent difficulties of technical writing • Typical projects and associated issues • Improving administration documentation 12/16/2021 5

Myths of Technical Writing The Documentation Decameron 12/16/2021 6

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 12/16/2021 7

Roles of a Technical Writer • Editing • Original writing • Maintaining documents • Producing online and web-based documentation 12/16/2021 8

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 12/16/2021 9

Roles of a Technical Writer • Cop – Policing consistency – Legal issues • Nudger • Tester • User Advocate 12/16/2021 10

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/16/2021 11

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 12/16/2021 12

Topics • Myths of technical writing • Inherent difficulties of technical writing • Typical projects and associated issues • Improving administration documentation 12/16/2021 13

Inherent Difficulties of Writing Documentation for System Administrators Care for some whine? 12/16/2021 14

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. 12/16/2021 15

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 12/16/2021 16

Inherent Difficulties Conflicting perspectives • Where information comes from vs. who it is for • Developer administrator marketer 12/16/2021 17

Inherent Difficulties No usability testing • Wonderful when possible • Time commitment • Best hope is informal 12/16/2021 18

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

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

Inherent Difficulties Hardware/software distinctions • True for development • Meaningless for administrators • Meaningless for field 12/16/2021 21

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? 12/16/2021 22

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 12/16/2021 23

Actual example of information quest 12/16/2021 24

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. 12/16/2021 25

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. 12/16/2021 26

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. 12/16/2021 27

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. 12/16/2021 28

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. . . 12/16/2021 29

A Writers Quest, Exhibit F Developer response: looks good! 12/16/2021 30

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 12/16/2021 31

Topics • Myths of technical writing • Inherent difficulties of technical writing • Typical projects and associated issues • Improving administration documentation 12/16/2021 32

Typical Projects and Associated Issues It’s always something 12/16/2021 33

Typical Projects • Man pages • Administrator guides • Procedures and examples • Online documentation • Others. . . 12/16/2021 34

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

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

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

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

Topics • Myths of technical writing • Inherent difficulties of technical writing • Typical projects and associated issues • Improving administration documentation 12/16/2021 39

Improving the Documentation A two-way street 12/16/2021 40

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

Improving the Documentation Contacting the writer • Document a problem you solved – What happened? – What did you do? – Will this help others? 12/16/2021 42

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 12/16/2021 43

Improving the Documentation Contacting the writer • Libraries of examples – Your personal procedures – Administrator tricks – Quirks and kludges 12/16/2021 44

Improving the Documentation Contacting the writer • What’s in it for you? – Helping others – Helping yourself 12/16/2021 45

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 12/16/2021 46

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

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 12/16/2021 48

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

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 12/16/2021 50

Roles of a Technical Writer • Editing • Coordinator • Original writing • Nudger • Maintaining documents • Tester • Producing online and web-based documentation • User advocate 12/16/2021 51

Roles of a Technical Writer • Detective • Cop 12/16/2021 52

The Linux Documentation Project http: //www. linuxdoc. org • Templates • Author guides • Mailing list 12/16/2021 53

The Linux Documentation Project • For documentation to improve: Needs to be used, feedback required • Existing mechanism for contacting writer • Changes can happen quickly in the open source world 12/16/2021 54

Improving the Documentation Summary • Contacting the writer Suggestions, examples, information networks • The village technical writer Collaborate within company • The global village technical writer Collaborate outside of company • Taking advantage of open source 12/16/2021 55

Conclusion At the other end of your document is somebody who is working with you: • To make the world run smoother • To take over the world 12/16/2021 56

Conclusion Envoi 12/16/2021 57