User:Pavithraes/Sandbox/Graphics in technical documentation

From MediaWiki.org
Jump to navigation Jump to search

Overview[edit]

Technical documentation provides explanations and descriptions of technical projects, products or processes. Sometimes, graphics can help communicate this information more clearly and more accurately than text alone. We discuss some graphics that can be used and how to use them best.

Purpose[edit]

Generally, graphics are used in technical documentation for one of the following purposes.

Purpose Description Example
Support text Graphics used along with textual information to validate it. Photos used with a story to prove authenticity
Replace text Graphics used instead of text to communicate some information. Using an illustration of agile development instead of plain writing.
Augment text Graphics used along with textual information enhance its impact. Comparative analysis graphs used with text.

Images[edit]

Always add a caption and/or a description of the image to improve the accessibility of the document.
Types Description Usage tips Example
Photographs A picture, usually representing a scene or an object, taken using a camera.
  • Use it to create a visual for an object or scene.
  • Make sure the image is clear and appropriately sized.
Screenshots A captured computer screen displaying some process.
  • Note the presence or absence of the cursor.
  • If there is text, make sure it is readable.
  • Consider resizing the image for better readability.
Illustrations, diagrams and schematics A digitally created representation (drawing) of a process.
  • Make sure the illustration follows basic design principles.
  • Label the diagram and reference it from the text.
Logos A digital icon used to represent a product or project.
  • Use it on the project landing pages.
  • Consider using it in the documentation template.
Posters A combination of images and text used to promote/explain a work product.
Charts, graphs and tables

A diagrammatic representation of data.

Videos[edit]

Include a translatable transcript and a descriptive caption for the video.
Type Description Usage tips Example
Screencasts Recording of a computer screen display.
  • Position the video near the related text and add necessary references.
  • Consider just adding a link vs embedding the video in the wiki.
Talk recordings Recording of a live talk, tutorial or workshop.
  • Include all necessary references, citations and slides in the document.
Animations Digitally created moving pictures.
  • Note the file-size of the animated video while embedding in a wiki.

See also[edit]