search

thegooddocsproject / templates

Templates created by The Good Docs Project - for all your tech writing needs.
https://thegooddocsproject.dev/
Other
681 stars 170 forks source link

Should we include images in our templates? If so, should we also establish a standardized size? #253

Open heykayla opened 2 years ago

heykayla commented 2 years ago

This question came up in a Community Docs meeting. A templateer wanted to know if they were allowed to integrate images or graphics in their template and asked if there was a standardized size for images they needed to follow.

camerons commented 2 years ago

Good question, with a few interpretations:

Q1: Should documentation include images? A1: There is some sound advice at: https://developers.google.com/style/images

Q2: Should images be used in the template.md. A2: I can't think of a reason to use them, unless they are being used as an example of how to use an image.

Q3: Should images e used in the guide.md. A3: Possibly, if the explanation is better done with an image, but probably not.

Note, images have a much higher cost of maintenance and translation than text. Consequently images have a high risk of becoming out of date. So we should try to avoid them.