Jean-Yves Perrier and Florian Scholz compares maintaining a large corpus of documents as planning and maintaining a garden. They present a few of the tools that has been built to maintain documentation.
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/
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
❏ ...
