Write The Docs, Prague, 2015 1

Gardening Open DocsFlorian Scholz & Jean-Yves Perrier

Write The Docs, Prague, 2015 2

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

Write The Docs, Prague, 2015 4

Different types of gardens

French GardensThe 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/

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/

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/

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 contributorsTransplant valuable editsReview edits https://www.flickr.com/photos/rhruzek/4420490349/

Write The Docs, Prague, 2015 8

Gardener challenges

DiseasesIllegal 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

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/

Write The Docs, Prague, 2015 10

Planning the gardenAutomatic monitoring Prioritization

Product management input

Write The Docs, Prague, 2015 11

Building pathways

Navigation is a hard problemSeveral entrancesMultiple goalsBridgesLadder to knowledge

No dead-endMapsFull accessibility

https://www.flickr.com/photos/werms/7076134605/

Write The Docs, Prague, 2015 12

Invite people on their way

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.

Write The Docs, Prague, 2015 14

MDN “meta” docs

I like code. I like words. I like both. I like MDN in my language.

Write The Docs, Prague, 2015 15

Jungle vs Garden

Jungle

No trails / navigationDoc trees not accessibleNo inventory

Experts won’t get lost here.

Garden

Garden is cultivatedNeeds waterNew seasons require work

Usually easier for beginners to get started.

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/

Write The Docs, Prague, 2015 17

arewedocumentedyet.comWhich gardens need help and in what way?

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❏ ...

Write The Docs, Prague, 2015 19

Tool: Before leaving...

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.comhttps://www.flickr.com/photos/raffywolfe/8692403782/