Image Sources

Within an enterprise documentation system, an image source is any application which produces image data either as their primary purpose (e.g., raster graphics editors) or as secondary, auxiliary capability (e.g., testing software, computational notebooks, etc.). As such, image sources are categorized into primary and secondary image sources.

Examples of primary image sources include:

Examples of secondary image sources include:

• Software Testing (Screenshot capture)
  • Cypress
  • Selenium
• Computational Notebooks (Data visualization)
  • Jupyter Lab
  • Wolfram Notebook
• Systems of Facts (e.g., burndown charts from Agile management software)
• Specialist Documentation Platforms (e.g., business process diagrams)

Sourcing Images

Unlike the more distinct differences between systems of dialogue and systems of facts, any application in an enterprise documentation systems may play the role of an image source, whenever image data requires specific processing for the embedding into documentation.

Truth Proximity

In DocOps, the principle of truth proximity requires us to avoid falling into the anti-pattern of having canonical information whose changes aren’t reflected in live documentation. As such, images must be retrieved from their canonical sources and converted automatically for their inclusion in documentation.

Examples

Images in Rich Document Formats

In simple scenarios, and when converting documents in one direction only, for example, when converting Markdown document that refers a number of PNG files to standard render format such as PDF, and when using a standard document conversion utility, the default result may be acceptable. However, in more advanced DocOps automation pipelines, images may be pre-processed so that they are optimized for each render target. For example:

• For the HTML render target (assuming AsciiDoc as the IDF):
  • Rasterize original SVG image to a medium-res RGB bitmap
  • Index RGB bitmap to 8 color (no dithering)
  • Save as PNG asset
  • Include specific image::image.png[...] parameters if appropriate
• For the PDF render target (assuming LaTeX as the IDF)
  • Convert original SVG image to Encapsulated PostScript
  • Save as EPS asset
  • Include specific \includegraphics[...] parameters if appropriate

DocOps Automation

In the case of primary image sources such as raster and vector graphics editors, most formats have a headless conversion approach to facilitate further processing. For example, ImageMagick can be used to convert an Adobe Photoshop’s PSD file into a JPG one for further processing.

The challenge is extracting images from secondary image sources which may not see themselves as members of an overarching enterprise documentation system. In this case, the DocOps engineer may need to reverse engineer such systems.