Sven Strack: The Importance of Documentation

I am working with Plone since 2006. Also involved in writethedocs.

I like to complain. Sometimes too picky? Working with Plone documentation I can get grumpy, sad, annoyed, angry. I will give a heavily opinionated talk. Please do not feel offended if I talk negatively about the documentation (or lack of it) of your package.

This talk is from a user point of view. You must realize that a good product is not just about the code. You look at the whole package. If the docs are broken, your product is broken.

On the Plone 5 release day, we had links to at least three different versions of Plone in the installer part. Confusing. Lots of old and not working or not checked code examples. Lots of confusing mixups between Archetypes and Dexterity. There were pending (not published) docs about theming. If you are a Plone consultant, you can find your way, or know who to ask, but as a user... No note that lots of add-ons are not working with Plone 5 yet. No note telling that some of the docs are not updated yet. The answer to a lot of questions on irc was: "The docs about X are not finished yet."

We forgot all of that, or had no time: our fault.

The technical stack is great. Plone 5 is ready as consultant-ware. For normal humans, the docs were not ready yet. Strictly spoken, we forgot to care about normal users.

You are done when it works and it is elegantly documented. Do at least something.

Documentation is marketing. It gets you new users much quicker. It can save a lot of time, effort, money.

Think about the process of documentation for your project as the true act of creation. Documentation Driven Development. I did not make this up!

1. You write Documentation.
2. You write Tests.
3. You write Code.

Simple!

You give yourself the chance to think the project through, without getting bogged down in a detail that you will rip out five minutes later.

Developer documentation is not end-user documentation.

It is much easier to write documentation at the beginning when you are still happy and excited about the project, instead of at the end when you are glad you have finally squashed most bugs and can ship it.

It is much easier to have a discussion based on something that you have written down.

Create an easy and friendly landing page. Make it easy to report a bug. Telling people to create an issue on github, is already too hard for some. We should add a link in the overview-controlpanel to docs.plone.org. Make it easy to find articles on docs.plone.org, the search is not great.

Know the audience you are writing for. Are you targeting end-users or developers. Don't assume readers have your skill set.

Always write a readme, even if it is not perfect. At least it is a starting point, and people can help you out.

Don't postpone writing docs, just add a few lines when you are coding.

Include docs testing in your CI setup. If you want to, you can even include automatic screen shots.

Configure your editor. There are plugins for editors, to check pep8, pyflakes, but also docs: ReStructuredText, spell check, maybe link checkers.

Use a git hook to check your documentation when you commit. Look at mr.butler, mr.docs. mr.docs is a Docker image with the same Sphinx setup that we use for docs.plone.org.

There is not one solution to fix it all.

Let's have an open space about improving the situation. Maybe a QA team?

And: docs or it didn't happen!

Questions?

The English of the documentation is sometimes really clear, and sometimes really complex. Simple is better, you may not even need translation then.

The new patterns have tested documentation in their Javascript. I don't think this gets included in docs.plone.org? No, it is not nearly enough. Nathan has written blog posts. The mockup documentation is not maintainable, at least it cannot be included currently, we need ReStructuredText. We are getting there, but the Javascript parts need much more work.

Patternslib has its own documentation. Do we just link to this, or do we want to include it? If it is in core, we want to include it. Patternslib documentation is in MarkDown, but that will work fine. We will have to try it and think what is in the long run most suited.