People that make complex applications may, over time, make custom little screenshots for bespoke tutorials or emails to their boss to say “look at this cool feature we have!”

This is nice, but this doesn’t really scale. These screenshots don’t tell the user the exact steps for how you did with your app, but making complex multi-step tutorials is hard to maintain over time with app changes, and so oftentimes, a tutorial is not even written leaving the knowledgebank of how to do things in your brain.

To externalize this brain-only content, you should to make documentation system more automated.

Specifically: you should make screenshots in your documentation 100% automated. You can likely make AI agents help you make the screenshots and puppeteer scripts

Make a helper app

I also recommend making your AI agent whip up a small ‘review’ webapp where you can review updated screenshots. In the review app I whipped up, it starts a local dev express.js server, and it has a textfield so you can specify if there is something wrong with the screenshot and it writes that to a reviews.json file.

Then i just periodically say ‘please read bad items in reviews.json and continue making fixes’

Automate the annotations on top of the tutorial images too

To truly improve the screenshots it is often necessary to an extra layer of ‘markup’ added to them. Before, you might manually have gone into powerpoint or mspaint to do this…that is a huge deterrant to continuously updating your docs. Make the annotations on your images automated too! Making accessible selectors on your webpages helps to locate elements on the page.

There are many benefits to this type of workflow

  • It forces you to exercise real high-value end-to-end user workflows that you want people to use. Similar to the Beyoncé rule from Google
  • It forces you to work on accessibility, because you should make your puppeteer scripts use simple selectors, not complicated ones
  • It forces you to think about navigating complex states in the app or even, supplying complex state tree snapshots (e.g. mobx-state-tree/zustand) as json or just more simple and bespoke url state (e.g. nuqs)

Conclusion

Ultimately, this makes your GUI documentation amenable to agentic improvement. I can just tell Claude “make a new tutorial for X” and voila it’s done. I am not a huge fan of AI generated text, but I can “let the screenshots do the talking”

There is no real excuse not to do this now, and the benefits are likely a big net positive! Now go out there and fix those docs

Footnote

You can also add things like a tolerance e.g. greater than 1% of px changed, etc. if you got some minor flakyness. i don’t necessarily regenerate all figures on every CI run, but periodically it should be automatable. after i started doing this, i very quickly expanded the number of screenshots in my docs almost 5x