why the documentation sucks and what you can do about it n.
Download
Skip this Video
Loading SlideShow in 5 Seconds..
Why the Documentation Sucks and What You Can Do About It PowerPoint Presentation
Download Presentation
Why the Documentation Sucks and What You Can Do About It

Loading in 2 Seconds...

play fullscreen
1 / 57

Why the Documentation Sucks and What You Can Do About It - PowerPoint PPT Presentation


  • 147 Views
  • Uploaded on

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.

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about 'Why the Documentation Sucks and What You Can Do About It' - sarai


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.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
sysadmin aptitude test
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 test1
Sysadmin Aptitude Test
  • User:System Administrator:: System Administrator:
  • (a) Marketing department
  • (b) Pointy-haired boss
  • (c) Technical writer
  • (d) Loki, creator of discord
topics
Topics
  • Myths of technical writing
  • Inherent difficulties of technical writing
  • Typical projects and associated issues
  • Improving administration documentation
slide6
Myths of Technical Writing
  • The Documentation Decameron
myths of technical writing
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
Roles of a Technical Writer
  • Editing
  • Original writing
  • Maintaining documents
  • Producing online and web-based documentation
roles of a technical writer1
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 writer2
Roles of a Technical Writer
  • Cop
    • Policing consistency
    • Legal issues
  • Nudger
  • Tester
  • User Advocate
myths of technical writing1
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 writing2
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
topics1
Topics
  • Myths of technical writing
  • Inherent difficulties of technical writing
  • Typical projects and associated issues
  • Improving administration documentation
slide15
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
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 difficulties1
Inherent Difficulties
  • Conflicting perspectives
  • Where information comes from vs. who it is for
  • Developer  administrator  marketer
inherent difficulties2
Inherent Difficulties
  • No usability testing
  • Wonderful when possible
  • Time commitment
  • Best hope is informal
inherent difficulties3
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 difficulties4
Inherent Difficulties
  • Short release cycles
  • Software freeze vs. documentation freeze
  • Small code changes/huge documentation changes
  • Continuous piecework
inherent difficulties5
Inherent Difficulties
  • Hardware/software distinctions
  • True for development
  • Meaningless for administrators
  • Meaningless for field
inherent difficulties6
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 difficulties7
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
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
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
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
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
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
A Writers Quest, Exhibit F
  • Developer response:
  • looks good!
inherent difficulties8
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
topics2
Topics
  • Myths of technical writing
  • Inherent difficulties of technical writing
  • Typical projects and associated issues
  • Improving administration documentation
typical projects
Typical Projects
  • Man pages
  • Administrator guides
  • Procedures and examples
  • Online documentation
  • Others...
typical projects1
Typical Projects
  • Man pages
  • Inconsistent
  • Unedited
  • Cumbersome to work on
  • Require vigilance to maintain
  • Low-status on department reports
typical projects2
Typical Projects
  • Administrator guides
  • Theory vs. procedure
  • Recovery procedures?
  • Many different audiences
  • Controversy: internals and system parameters
typical projects3
Typical Projects
  • Procedures
  • What are useful procedures?
  • System availability
  • System setup
  • Same requirements as testing/QA
typical projects4
Typical Projects
  • Online documentation
  • True online vs. screen-displayed manuals
  • Technical support required
  • Notification of updates
topics3
Topics
  • Myths of technical writing
  • Inherent difficulties of technical writing
  • Typical projects and associated issues
  • Improving administration documentation
improving the documentation
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 documentation1
Improving the Documentation
  • Contacting the writer
  • Document a problem you solved
    • What happened?
    • What did you do?
    • Will this help others?
improving the documentation2
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 documentation3
Improving the Documentation
  • Contacting the writer
  • Libraries of examples
    • Your personal procedures
    • Administrator tricks
    • Quirks and kludges
improving the documentation4
Improving the Documentation
  • Contacting the writer
  • What’s in it for you?
    • Helping others
    • Helping yourself
improving the documentation5
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 documentation6
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 documentation7
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
Linux and Open Source
  • Collective administration experience
  • Complainers can fix things
  • Contribute to documentation: credited by name
linux and open source1
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
roles of a technical writer3
Editing

Original writing

Maintaining documents

Producing online and web-based documentation

Coordinator

Nudger

Tester

User advocate

Roles of a Technical Writer
the linux documentation project
The Linux Documentation Project
  • http://www.linuxdoc.org
  • Templates
  • Author guides
  • Mailing list
the linux documentation project1
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
improving the documentation8
Improving the Documentation
  • Summary
  • Contacting the writerSuggestions, examples, information networks
  • The village technical writerCollaborate within company
  • The global village technical writer Collaborate outside of company
  • Taking advantage of open source
conclusion
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