Effectively Managing Documentation for Open Source Projects Jeff - - PowerPoint PPT Presentation

▶
effectively managing documentation
SMART_READER_LITE
LIVE PREVIEW

Effectively Managing Documentation for Open Source Projects Jeff - - PowerPoint PPT Presentation

Oct 10, 2022 4.85k likes •5.31k views

Effectively Managing Documentation for Open Source Projects Jeff Osier-Mixon OSCON 2010 Today 1 subject for today: documentation 2 things to avoid in documentation 3 qualities of solid documentation 4 classical elements 5 readers you must

slide-1
SLIDE 1

Effectively Managing Documentation

for Open Source Projects Jeff Osier-Mixon

OSCON 2010

slide-2
SLIDE 2

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

slide-3
SLIDE 3

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

slide-4
SLIDE 4

What is documentation?

  • first contact – presentation
  • source of education – training
  • front line of support – troubleshooting
slide-5
SLIDE 5

What is documentation?

  • conceptual material
  • “how-to” information
  • reference material
  • troubleshooting
slide-6
SLIDE 6

What is documentation?

communication with people who care about your project

slide-7
SLIDE 7

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

slide-8
SLIDE 8

Two Things to Avoid

  • perfection
  • forgetting that your audience

is people

slide-9
SLIDE 9

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

slide-10
SLIDE 10

Qualities of Solid Documentation

What is not solid?

  • missing unmentioned features

(TBD is OK)

  • inconsistent
  • unprofessional
slide-11
SLIDE 11

Qualities of Solid Documentation

  • complete
  • correct
  • appropriate
slide-12
SLIDE 12

Qualities of Solid Documentation

Complete

  • covers all features, usage modes, and

interfaces

  • answers essential questions

(what, how, where)

  • consistent & professional
slide-13
SLIDE 13

Qualities of Solid Documentation

Correct

  • matches the software, hardware, or

device which it targets

  • logically organized
  • consistent & professional
slide-14
SLIDE 14

Qualities of Solid Documentation

Appropriate to audience

  • know who the audience is
  • know what they need to know
  • answer their questions
  • accessible
  • consistent & professional
slide-15
SLIDE 15

Qualities of Solid Documentation

What is less important?

  • text format – fonts, colors…
  • tools – XML, FrameMaker, nroff, Word
  • delivery format – HTML, PDF, print
  • perfection
slide-16
SLIDE 16

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

slide-17
SLIDE 17

Critical Elements

  • Concepts
  • Tasks & Examples
  • Reference
  • Troubleshooting
slide-18
SLIDE 18

Critical Elements

Concepts

  • the Big Picture from 10,000 ft
  • overview, introductory material
  • brochures, white papers, web pages
  • architecture guides
  • focus on education
slide-19
SLIDE 19

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
slide-20
SLIDE 20

Critical Elements

References

  • the 0-foot view
  • system reference manuals
  • layout, manufacturing, API guides
  • maximal cross-references
  • focus on completeness
slide-21
SLIDE 21

Critical Elements

Troubleshooting

  • the -6 foot view, looking backward
  • step-by-step diagnostics, flowcharts
  • FAQs
  • from the reader’s perspective
  • focus on answering questions
slide-22
SLIDE 22

Critical Elements

Four-element theme is recursive:

Concepts Tasks & Examples Reference Trouble- shooting Doc set in general Overview & Specs

  • Prog. Guides

Tutorials API Guides

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

slide-23
SLIDE 23

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

slide-24
SLIDE 24

Readers

  • Partners
  • Developers
  • Internal
  • End-users
  • Community
slide-25
SLIDE 25

Readers

Partners

  • people who sell, extend, promote,
  • r add value to your project
slide-26
SLIDE 26

Readers

Developers

  • people who use your project as basis for

creating products of their own

slide-27
SLIDE 27

Readers

Internal

  • people in your organization
slide-28
SLIDE 28

Readers

End-users

  • people who use the end result of the

above activities (and sometimes pay for the privilege)

slide-29
SLIDE 29

Readers

Community

  • people who care about your project

by choice

slide-30
SLIDE 30

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

slide-31
SLIDE 31

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?
slide-32
SLIDE 32

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

slide-33
SLIDE 33

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 toBe Understood

  • Habit 6: Synergize
  • Habit 7: Sharpen the Saw
slide-34
SLIDE 34

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

  • thers, when looking at optimistic

people.”

slide-35
SLIDE 35

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

  • thers. ”
slide-36
SLIDE 36

7 Habits of Highly Effective…

abundance mentality == open source: “Individuals with an abundance mentality celebrate the success of

  • thers rather than be threatened by

it.”

slide-37
SLIDE 37

Other Resources

  • FLOSS Manuals (flossmanuals.net)
  • pen-source doc project framework
  • eLinux.org

wiki for embedded Linux

  • tldp.org

The Linux Documentation Project

  • Linux.com
  • Your Community

for the projects you care about

slide-38
SLIDE 38

Jeffrey Osier-Mixon

408 MR OSIER jefro@jefro.net http://www.jefro.net @jefro.net