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.
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.
- 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.
- 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.
Comments
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:
- Recommendations for writing good Alt Text for your screenshots
- Does the title attribute on images help with SEO?
- When are product screenshots most helpful?
- Will AI image recognition help with screenshot automation in the future?
- Recommendations for image file formats
- What is the right ratio of images to text?
- Are GIFs better than screenshots with callouts?
- How to automate screenshots that illustrate product capabilities?
Got a question on product screenshots that wasn’t answered? Feel free to connect with us (Dennis, Josh) or email hello@launchbrightly.com and ask directly! We’re always happy to chat :-)