By Dennis Mortensen In Events, WTD | September 2023

When to add images in developer-focused documentation? (WTD Atlantic 2023)

We were chuffed to have been chosen to host a talk on The Power of Product Screenshots in your Help Documentation at the Write the Docs Atlantic conference on September 12. It was a great couple of days learning all things software documentation with the passionate and engaging community that is Write the Docs. Thank you to everyone who took the time to listen to our talk and for all the thoughtful questions throughout.

LaunchBrightly The Power of Product Screenshots WTD Atlantic

Q: In developer-focused documentation, where can we add imagery? Code snippets seem to be just more text (altho definitely important!) - Heather Wilkins

As a developer myself, I absolutely love when documentation has code snippets with proper syntax highlighting that is easy to copy for the particular programming language I use (just like Michelle said in the comments). So I, like many of my programmer friends, dislike when these are turned into images. I would recommend against that (which is not what you are suggesting, so just a Public Service Announcement, he he). Let me add two examples though.

  1. I do think many of the developer-focused documentation destinations I look at are missing an opportunity in showing the expected outputs. Sometimes this is as easy as providing another, say JSON code snippet for e.g. an API. But more often than not, this requires visuals as we can neither run the code or show in text what the output would look like given a set of unique parameters / use-cases.
  2. Many times developer focused products, such as e.g. Stripe or Twilio (big fan of both) comes with a management portal of sorts, and I am a big fan of injecting those product screenshots directly into the places where you are making API calls that allows for or depends on portal settings. You can request a set of active phone numbers on Twilio, but it is also very valuable IMHO to show where to find that info in the portal.

In closing, and as Abi suggests, wherever possible, I would recommend diagrams and schematics to help expose typically hidden information on subjects like infrastructure et al.


Michelle: I have found that using a screenshot with color code highlighting helps me understand code better. Maybe that is one opportunity?

Abi: Architectural and conceptual diagrams. Remember that some people learn faster and easier through visual means; others through verbal. (Think about who loves and who hates IKEA instructions.)

Abi: So one user may want to read that the knee bone is connected to the leg bone, but another may want a picture of a skeleton.

You can see a summary of the talk and find a link to the recording here.

And you can also find a link to the other great questions from the chat below:

Got a question on product screenshots that wasn’t answered? Feel free to connect with us (Dennis, Josh) or email and ask directly! We’re always happy to chat :-)