Paul Roeland and Sven Strack: Cultural Learnings of Documentation for Make Benefit Glorious Nation of Plonistan
Talk by Paul Roeland and Sven Strack at the Plone Conference 2014 in Bristol.
If you still think documentation is about "how stuff works", you are doing it wrong. There is a lot of software around, people have lots of choices, people being future clients, developers, users, community members.
Also, your future self will thank you. It is good to know what that idiot was thinking half a year ago.
Sometimes you just want to use a four letter word: RTFM. Read the fine manual. But then there has to be a manual. If people don't know Plone, they won't use it.
A year ago, in Brasilia, a plan was born. We were really unhappy with the state of documentation last year. Spread around over the internet.
A robot master, documenter, marketeer and 9 others walk into a bar and... Well, it was an office, well there was a bar involved, but anyway. Sisi Nutt did a lot there. Without her the documentation would not be so far as it is now. It has been tested on live humans (testing on animals is not allowed).
We had a reality check on the Write The Docs conference in Berlin. Good to get input and feedback from other people. We are now testing broken links using continuous integration, which was new to them.
So now we want more, better, nicer, shinier, sweeter. What we are now telling about documenting Plone, you should apply that to your add-ons too. If it is not documented, it is not used.
- Define what the audience is of your documentation, or for a specific part of your documentation. Structure your docs accordingly.
- Soft landings are important. So add introductions. Let people see if this chapter is what they are looking for.
- Get the tone right. Friendly and professional go a long way. Don't scare off users, unless you really want to. Ask for help, especially if English is not your first language.
- Consistency. Don't leave your readers hanging, nor your contributors. Always use the same terminology. Write and follow style guides. Do not make it too complicated. Read the Zen of Python (import this) and apply it to your documentation as well.
- Versioning. Different software versions need different docs. Benefit: you can retire the old. This is what we will do soon. On http://docs.plone.org you will see the Plone 4 docs by default, and can choose a different version.
- Spellcheck is a wonderful invention, please use it.
- We love humor. Please do not do that in documentation. Highly culturally charged. It gets old quickly and docs are meant to last.
- Sarcasm is never a good idea in docs. Nor in irc, for that matter.
- Testing is essential. Test it on somebody who is not an expert in the field. Does your audience get it?
Now for some tools. Search docs right from Sublime. It has integrated search for Chrome, Firefox, DuckDuckGo. Or using Dash (OS X) and Zeal (Windows, Linux).
Quality control. We have robot screenshots. Automated spell check. We add some words to the known words list, which doubles as a Kudo list, for example we have added David Glick to that list, otherwise we get errors from the spell check.
Challenge
As a project we need documentation. It is not hard, it is just something you need to start doing. We need to get to work.
- We need people with deep skills. For example, a lot of documentation is using grok, which is not recommended anymore, so can someone please update that.
- We need people new to Plone. Get an intern to read and try out the documentation, to see if it is still correct.
- We need help translating at least end user documentation.
- Use semantic line breaks, not just after 79 characters, because half sentences are really hard to translate.
- We need Python developers too for creating some code for helping to create the docs.
- Please put some energy in it, also time from your company, pretty please. The 10 percent Plone manifesto is still good.
Is there a Plone style guide? There is a beginning, needs extension. It is in the How to contribute section.