The document discusses the challenges and strategies involved in effectively managing and improving documentation as a collaborative effort, likening the process to gardening. It highlights the necessity of planning, monitoring, and inviting contributions while addressing potential issues like misinformation and inappropriate content. The authors advocate for a balance between structure and flexibility in documentation to foster a vibrant and accessible community resource.

1. Write The Docs, Prague, 2015 1
Gardening Open Docs
Florian Scholz &
Jean-Yves Perrier

2. Write The Docs, Prague, 2015 2

3. Write The Docs, Prague, 2015 3
An heterogenous
corpus
Open Web
Beginner content
English
Expert-made
Experimental tech.
Mozilla products
Expert content
41 other languages
Learner-made
Mature technologies

4. Write The Docs, Prague, 2015 4
Different types of gardens
French Gardens
The triumph of Geometry
Used by traditional media.
The dictatorship of the plan:
‒ Defined before the building start.
‒ Strictly followed.
https://www.flickr.com/photos/odlagz/5265367815/

5. Write The Docs, Prague, 2015 5
Different types of gardens
British Gardens
“Since gardens (…) work with
material that grows and decays,
keeping them in good shape is a
design issue.”
Lodewijk Baljon,
famous Dutch landscaper
Wiki provides:
‒ Flexibility
‒ Parallelism
‒ Reuse / remixhttps://www.flickr.com/photos/simonov/14601290250/

6. Write The Docs, Prague, 2015 6
Gardener challenges
You don’t start with a ready-to-farm field, but with a jungle.
https://www.flickr.com/photos/vissago/2903489440/ https://www.flickr.com/photos/cewe/4561467390/

7. Write The Docs, Prague, 2015 7
Gardener challenges
Bad weeds
‒ Orthographic, grammatical,
and typographic errors
‒ Misplaced edits
‒ Small factual errors
Appears more often on wasteland
On-boarding new contributors
Transplant valuable edits
Review edits https://www.flickr.com/photos/rhruzek/4420490349/

8. Write The Docs, Prague, 2015 8
Gardener challenges
Diseases
Illegal and inappropriate content like:
‒ copyright violations,
‒ pornography,
‒ … (worse).
Like for fire blight, the authorities
can burn your garden.
Invasive plants
‒ Spam
‒ Misshaped refactorization
Make the garden plants suffocate and
kill them.
https://www.flickr.com/photos/ngawangchodron/14820021418 https://www.flickr.com/photos/dharmasphere/16598562313

9. Write The Docs, Prague, 2015 9
Planning the garden
Which species to choose?
https://www.flickr.com/photos/martinlabar/2417636285/ https://www.flickr.com/photos/martinlabar/7928914808/ https://www.flickr.com/photos/jim-sf/4439964275/

10. Write The Docs, Prague, 2015 10
Planning the garden
Automatic monitoring Prioritization
Product management input

11. Write The Docs, Prague, 2015 11
Building pathways
Navigation is a hard problem
Several entrances
Multiple goals
Bridges
Ladder to knowledge
No dead-end
Maps
Full accessibility
https://www.flickr.com/photos/werms/7076134605/

12. Write The Docs, Prague, 2015 12
Invite people on their way

13. Write The Docs, Prague, 2015 13
Gardening tools
https://www.flickr.com/photos/pleuntje/5809787537/
The community is
diverse and
cultivates the
garden in many
ways.
Help is needed in
which garden to use
which tool and how.

14. Write The Docs, Prague, 2015 14
MDN “meta” docs
I like code. I like words.
I like both. I like MDN in my language.

15. Write The Docs, Prague, 2015 15
Jungle vs Garden
Jungle
No trails / navigation
Doc trees not accessible
No inventory
Experts won’t get lost
here.
Garden
Garden is cultivated
Needs water
New seasons require work
Usually easier for
beginners to get started.

16. Write The Docs, Prague, 2015 16
Observe your garden
Know who is doing
what in your
gardens.
Which areas are
about to become a
wild jungle again?
https://www.flickr.com/photos/minhocos/13950908853/

17. Write The Docs, Prague, 2015 17
arewedocumentedyet.com
Which gardens need help and in what way?

18. Write The Docs, Prague, 2015 18
Doc status criterias
❏ Pages with no tags
❏ Pages with Needs* tags
❏ Editorial reviews needed
❏ Technical reviews needed
❏ Outdated pages
❏ Missing pages
❏ Documentation bugs filed
❏ ...

19. Write The Docs, Prague, 2015 19
Tool: Before leaving...

20. Write The Docs, Prague, 2015 20
Smell the flowers,
read the docs,
listen to the birds,
and… relax!
Thank you!
@floscholz, fscholz@mozilla.com @teoli2003, jperrier@mozilla.com
https://www.flickr.com/photos/raffywolfe/8692403782/