Screenshots
Adding screenshots to documentation is tricky because it can be helpful, but it also has some major drawbacks. I tried to read up on the subject and found some useful resources:
- https://writing.stackexchange.com/questions/10643/when-is-a-screenshot-really-useful-in-training-documentation
- https://developer.gnome.org/gdp-style-guide/stable/infodesign-8.html.en#infodesign-10
- http://user-assistance.blogspot.com/2009/10/screen-shots-in-documentation.html
With those in mind I propose the following policy for screenshots:
- The overview should contain a screenshot that is representative of castellum as a whole
- Screenshots should be used (sparingly) for guides to reassure users that they are in the correct location
- cluster guides
- only if the screenshot is easily recognizable
- Screenshots should be used (sparingly) for guides to illustrate complex or unfamiliar interactions
- Screenshots only support the text, never replace it
- Screenshots should be taken
- without the yellow "demo mode" banner
- with the sample AttributeDescriptions
- with an admin user or, if relevant for the specific case, with the relevant demo user
- preferably of the whole page
- in english (german translation might be added later)