Cultural Learnings of Documentation for Make Benefit Glorious Nation of Plonistan
Paul Roeland & Sven Strack
Plone Conference 2014, Bristol
It's 2014, people...
If you still think documentation is about "how stuff works"
You're doing it wrong
for new users, decision makers, interested people
(a.k.a. future clients & future community members)
Shocking, isn't it?
But wait, there's more reasons to write docs..
Your future self
“You will be using your own code six months from now.”
and even if you want to be bad
Of course you're all way too nice to use Four Letter Words.
but we've all thought about a few
To point people to a Fine Manual,
there has to be a Fine Manual
If people don't know why Plone exists
they won't use it
If people can’t figure out how to install Plone
they won't use it
If people can’t figure out how to use Plone
thanks, Hedy Lamarr
for spread spectrum,
... and the fabulousness
Now for the good stuff...
Much has already been done
Let's do some quick time-travelling...
A year ago...
a plan was born
To stay forever on the beach
ehm, to unify all Plone documentation
A robot master, a documenter, a marketeer and 9 others walk into a bar...
(actually, it was more an office)
but still, much was achieved, thanks to a wide variety of people
Thanks, Sisi Nutt!
After a lot of productive discussions...
... and some more sprints...
the new docs.plone.org was born
“Never use a long word
where a short one will do”
we want MORE
So many choices...
So this goes for all you add-on authors too!
Define them (however broadly)
and structure your docs accordingly
Soft landings are important
Each chapter needs a landing page,
so people can see if this is what they were looking for
Friendly & professional go a long way...
- Don't leave your readers hanging...
- ... nor your contributors
- Always use the same terminology
- Follow (or write!) the styleguides
- Use concise, simple paragraphs
... hang on, we know this stuff!
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Now is better than never.
Different software versions need different docs
Which has as great benefit:
You can gracefully retire the old!
Spellcheck is a wonderful invention
as are grammar tools.
They're like “lint” for natural language ;-)
- It's a double-edged sword
- Highly culturally charged
- Gets old quickly, docs are meant to last
- So maybe not.
is never a good idea in docs.
nor IRC, for that matter
testing is essential
not only for correctness in formatting
but also as in does my audience get it?
- Search docs right from Sublime
- Integrated search in Chrome, Firefox, DuckDuckGo, ...
- Dash (OS X) & Zeal (Win/Linux)
- robot screenshots
- Docker & friends deployment
- Continuous Integration
- automated spellcheck
which doubles as a nice Kudo system ;-)
so now we come to:
If this is your
feeling as a dev...
(OH GOD I'M BORED)
Get to work...
All skills & all skill levels welcome!
New staff? Ask them to document their journey!
Speaking in tongues? Help translate!