Screenshots in documentation can be a contentious topic — some people really like them and think they add a lot of value, while others dislike them due to the maintenance burden and accessibility issues. So what should you do?

Hacker News is a community-driven platform for sharing and discussing technology news, startups, and programming-related topics. Through user submissions and comments, Hacker News offers insights into emerging technology trends, industry developments, and entrepreneurial ventures. Readers can participate in discussions, share their insights, and stay informed about the latest advancements in technology and innovation.

Hacker News

Screenshots in documentation can be contentious. Outdated screenshots can decrease customer trust and slow down page loading. However, they can also make content easier to scan, provide a visual frame of reference, and supplement confusing task steps. To effectively use screenshots, it is important to consider their purpose, make them accessible, use simplified versions, and automate their creation and maintenance when possible.

Should you add screenshots to documentation?

Intentionally add images to your documentation

Yes some people like myself learn better with visuals.

This article, written by Sarah Moir on December 10, 2023, discusses the contentious topic of including screenshots in documentation. It explores both the advantages and disadvantages of this practice from the perspective of a technical writer.
Disadvantages of Screenshots:
<ol>
<li>Trust Issues: Outdated screenshots can quickly diminish customer trust in the documentation’s accuracy.</li>
<li>Performance Impact: Pages with numerous screenshots load slower than text-only pages.</li>
<li>Loss of Explanation: Screenshots can replace detailed step-by-step instructions, losing the rationale behind performing a task.</li>
<li>Accessibility Concerns: Many screenshots lack effective alternative text, making them inaccessible to individuals with vision impairments.</li>
<li>Overemphasis on UI: Reliance on screenshots may lead to documentation that focuses excessively on the user interface, neglecting explanations of functionality or data interpretation.</li>
</ol>
Despite these concerns, the author acknowledges that these issues are mostly related to implementation and can be addressed.
Advantages of Screenshots:
<ol>
<li>Enhanced Scannability: Screenshots allow readers to quickly find relevant sections.</li>
<li>Visual Reference: They provide a visual frame of reference, especially useful for readers not using the product simultaneously.</li>
<li>Clarity in Instructions: When used appropriately, screenshots can clarify complex steps in a process.</li>
</ol>
The article references a study by the Baymard Institute, highlighting the importance of visual elements in SaaS products to enhance user understanding. However, the constant updating of UIs in SaaS products complicates maintaining accurate screenshots.
Strategies for Using Screenshots Effectively:
<ol>
<li>Purposeful Inclusion: Screenshots should be used to clarify confusing pages, give a sense of page appearance with data, or guide users through multi-page tasks. They should be avoided as mere fillers or for purely decorative purposes.</li>
<li>Accessibility: It’s crucial to ensure screenshots are accessible. This includes writing effective alt text (referencing Microsoft’s guide) and considering image file sizes for faster page loading.</li>
<li>Use of Simplified Screenshots: To reduce maintenance, screenshots can be simplified by obscuring irrelevant content. This approach requires less frequent updates.</li>
<li>Automation of Screenshots: For those with the capability, automating screenshot creation and maintenance can be a viable option, using tools like Simon Willison’s ‘shot-scraper.’</li>
</ol>
Conclusion:
The article emphasizes the importance of a strategic and intentional approach to adding images in documentation. By doing so, one can enjoy the benefits of screenshots while minimizing their drawbacks. The article also advises against over-reliance on screenshots for UI reference content, suggesting a more audience-focused approach to documentation.
done with GPT

i would say : exploit every tool you have to explain a complex concept.