Plone Visual Documentation Experiment

Adding Screenshots to Documentation

I've believed for a while that the Plone documentation in general could benefit from some useful screenshots. To test my theory I headed over to developer.plone.org for a short experiment to see what screenshots might do for a document.

As a proof of concept I wanted to see the extent to which adding a few strategic screenshots to a tutorial might improve the experience of learning Plone. I decided to use a tutorial that I thought would do well with screenshots, check out the screenshot version at creating forms with PloneFormGen.

Before screenshots

Here is the before picture of the entire document.

After screenshots

Here's a screenshot of a section where I added a supporting screenshot:

Methodology

The general approach was to follow the tutorial, identify where to put supporting screenshots, create the screenshots then add them.

I decided to read through the documentation and note where a screenshot or diagram would be appropriate with an SSS or DDD. Then I would replace all the SSSs with appropriate screenshots and DDDs will be replaced with diagrams.

In the first step my file has little SSS notes.

A replaced SSS looks like this:

Outcome and Observations

I ended up only using screenshots this time around (no DDD diagrams) but I'll definitely have scenarios where diagrams are more appropriate in the future.  I used animated gifs instead of flash or something else because they will be viewable when creating printed versions of the documentation.  I think the simple animations help to illuminate some of the explanations in the documentation.

Future and Possible Improvements

I can see this approach being very helpful at documentation sprints and it would give a newbie experience with specific Plone features while they create screenshots as well as gaining experience with revision management procedures.

It would be good to review the screenshots and see how they can be optimized so they best support the documentation. I'd love to look at options for streamlining the process of creating the gifs as it was quite cumbersome.