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.
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.
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.
No comments:
Post a Comment