Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively...
Transcript of Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively...
![Page 1: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/1.jpg)
Effectively Managing Documentation
for Open Source Projects
Jeff Osier-MixonOSCON 2010
![Page 2: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/2.jpg)
Today
1 subject for today: documentation
2 things to avoid in documentation
3 qualities of solid documentation
4 classical elements
5 readers you must satisfy
6 critical questions
7 habits for managing the process effectively
![Page 3: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/3.jpg)
Today
1 subject for today: documentation
2 things to avoid in documentation
3 qualities of solid documentation
4 classical elements
5 readers you must satisfy
6 critical questions
7 habits for managing the process effectively
![Page 4: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/4.jpg)
What is documentation?
• first contact – presentation
• source of education – training
• front line of support – troubleshooting
![Page 5: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/5.jpg)
What is documentation?
• conceptual material
• “how-to” information
• reference material
• troubleshooting
![Page 6: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/6.jpg)
What is documentation?
communication with people who care about your project
![Page 7: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/7.jpg)
Today
1 subject for today: documentation
2 things to avoid in documentation
3 qualities of solid documentation
4 classical elements
5 readers you must satisfy
6 critical questions
7 habits for managing the process effectively
![Page 8: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/8.jpg)
Two Things to Avoid
• perfection
• forgetting that your audience is people
![Page 9: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/9.jpg)
Today
1 subject for today: documentation
2 things to avoid in documentation
3 qualities of solid documentation
4 classical elements
5 readers you must satisfy
6 critical questions
7 habits for managing the process effectively
![Page 10: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/10.jpg)
Qualities of Solid Documentation
What is not solid?
• missing unmentioned features (TBD is OK)
• inconsistent
• unprofessional
![Page 11: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/11.jpg)
Qualities of Solid Documentation
• complete
• correct
• appropriate
![Page 12: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/12.jpg)
Qualities of Solid Documentation
Complete
• covers all features, usage modes, and interfaces
• answers essential questions(what, how, where)
• consistent & professional
![Page 13: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/13.jpg)
Qualities of Solid Documentation
Correct
• matches the software, hardware, or device which it targets
• logically organized
• consistent & professional
![Page 14: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/14.jpg)
Qualities of Solid Documentation
Appropriate to audience
• know who the audience is
• know what they need to know
• answer their questions
• accessible
• consistent & professional
![Page 15: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/15.jpg)
Qualities of Solid Documentation
What is less important?
• text format – fonts, colors…
• tools – XML, FrameMaker, nroff, Word
• delivery format – HTML, PDF, print
• perfection
![Page 16: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/16.jpg)
Today
1 subject for today: documentation
2 things to avoid in documentation
3 qualities of solid documentation
4 classical elements
5 readers you must satisfy
6 critical questions
7 habits for managing the process effectively
![Page 17: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/17.jpg)
Critical Elements
• Concepts
• Tasks & Examples
• Reference
• Troubleshooting
![Page 18: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/18.jpg)
Critical Elements
Concepts
• the Big Picture from 10,000 ft
• overview, introductory material
• brochures, white papers, web pages
• architecture guides
• focus on education
![Page 19: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/19.jpg)
Critical Elements
Tasks & Examples
• the 10-foot overhead view
• step-by-step user & “quick-start” guides
• tutorials, training materials
• minimal cross-references
• focus on usability & consistency
![Page 20: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/20.jpg)
Critical Elements
References
• the 0-foot view
• system reference manuals
• layout, manufacturing, API guides
• maximal cross-references
• focus on completeness
![Page 21: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/21.jpg)
Critical Elements
Troubleshooting
• the -6 foot view, looking backward
• step-by-step diagnostics, flowcharts
• FAQs
• from the reader’s perspective
• focus on answering questions
![Page 22: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/22.jpg)
Critical Elements
Four-element theme is recursive:Concepts Tasks &
ExamplesReference Trouble-
shooting
Doc set in general
Overview & Specs
Prog. Guides
Tutorials
API GuidesGlob. Index
Search function
FAQs
KBs
Each document Prefatory chapters
“How-To” chapters
Appendices
Index
Optional trouble-shooting sec.
Each chapter Overview Task and example sections
Cross-refs to reference documents
Cross-refs to related information
Each individual document element
Introduce topic, task, example
Step by step instructions
Cross-refs to reference documents
Cross-refs to related information
![Page 23: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/23.jpg)
Today
1 subject for today: documentation
2 things to avoid in documentation
3 qualities of solid documentation
4 classical elements
5 readers you must satisfy
6 critical questions
7 habits for managing the process effectively
![Page 24: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/24.jpg)
Readers
• Partners
• Developers
• Internal
• End-users
• Community
![Page 25: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/25.jpg)
Readers
Partners
• people who sell, extend, promote, or add value to your project
![Page 26: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/26.jpg)
Readers
Developers
• people who use your project as basis for creating products of their own
![Page 27: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/27.jpg)
Readers
Internal
• people in your organization
![Page 28: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/28.jpg)
Readers
End-users
• people who use the end result of the above activities (and sometimes pay for the privilege)
![Page 29: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/29.jpg)
Readers
Community
• people who care about your project by choice
![Page 30: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/30.jpg)
Today
1 subject for today: documentation
2 things to avoid in documentation
3 qualities of solid documentation
4 classical elements
5 readers you must satisfy
6 critical questions
7 habits for managing the process effectively
![Page 31: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/31.jpg)
Critical Questions
• What is it?
• Why do I need it?
• What does it look like?
• Who’s going to make it?
• Where do I put it?
• When do I schedule it?
![Page 32: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/32.jpg)
Today
1 subject for today: documentation
2 things to avoid in documentation
3 qualities of solid documentation
4 classical elements
5 readers you must satisfy
6 critical questions
7 habits for managing the process effectively
![Page 33: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/33.jpg)
7 Habits of Highly Effective…
• Habit 1: Be Proactive
• Habit 2: Begin with the End in Mind
• Habit 3: Put First Things First
• Habit 4: Think Win/Win
• Habit 5: Seek First to Understand, Then to Be Understood
• Habit 6: Synergize
• Habit 7: Sharpen the Saw
![Page 34: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/34.jpg)
7 Habits of Highly Effective…
abundance mentality == open source:
“…a business concept in which a person believes there are enough resources and success to share with others, when looking at optimistic people.”
![Page 35: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/35.jpg)
7 Habits of Highly Effective…
abundance mentality == open source:
“It is commonly contrasted with the scarcity mindset, which is founded on the idea that, given a finite amount of resources, a person must hoard their belongings and protect them from others. ”
![Page 36: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/36.jpg)
7 Habits of Highly Effective…
abundance mentality == open source:
“Individuals with an abundance mentality celebrate the success of others rather than be threatened by it.”
![Page 37: Effectively Managing Documentation - O'Reilly Mediaassets.en.oreilly.com/1/event/45/Effectively Managing Documentation... · •source of education –training ... introductory material](https://reader031.fdocuments.us/reader031/viewer/2022021505/5aed78b97f8b9a572b8b549e/html5/thumbnails/37.jpg)
Other Resources
• FLOSS Manuals (flossmanuals.net)open-source doc project framework
• eLinux.orgwiki for embedded Linux
• tldp.orgThe Linux Documentation Project
• Linux.com
• Your Communityfor the projects you care about