Images or figures grab the reader’s attention and convey information that sometimes is difficult to explain using words alone. Well-planned graphics reduce the amount of text required to explain information. Non-native English readers rely heavily on graphics because graphics enhance their understanding of the text.

Follow these guidelines when creating graphics for the Clear Linux* OS:

  • Save the image files in a figures folder. The folder must be found at the same level as the file containing the text.
  • Use only lower case letters for image filenames.
  • Separate multiple words in filenames using dashes.
  • Name figures with the filename of the file they appear on and add a number to indicate their place in the file. For example: The third figure added to the fibers.rst file must be named fibers-3.png.
  • Include a caption describing the figure’s content and to use as a reference. All figures must have a caption.
  • Use cross-references. Refer to your graphics in the main text flow. Create a label using the filename of the image. Use the :ref: role to place the cross reference, see Cross-references for more details.
  • Place the figure immediately after its reference in the text flow or as close as possible.
  • Keep figures simple. They should only contain the information the reader needs.
  • Use figures judiciously. Don’t use superfluous graphics and don’t use graphics as mere decorations. They must have purpose. You don’t need to show a screenshot of every single step or window in a software installation procedure, for example.
  • Avoid volatility. Don’t incorporate information into a graphic that might change with each release, for example: product versions or codename abbreviations.
  • Use only approved image formats. Use either PNG or JPEG bitmap files for screenshots and SVG files for vector graphics. If a figure is not a photograph or screenshot, use the vector graphic file format to ensure the figure can be changed later.

Examples

These examples follow the guidelines and can be used as a reference.

The fiber context is represented in the diagram either as a box containing different objects or a symbol.

Fibers Execution Context Symbol

The graphic representation of the fibers execution context.

This symbol is used to illustrate the actions performed by the abstract fibers execution context.

Templates

Use this template to add a figure to your documentation according to these guidelines.

.. _file-name-#.ext:

.. figure:: figures/file-name-#.ext
   :scale: 75%
   :alt: Alternative text.

   Figure 1: Brief caption detailing the contents of the image.

   Any additional explanation, description or actions depicted in the
   image. It can encompass multiple lines.