#Screenshots automation
fossil fox
It is procedural
it runs HA and acts like an user
So, how I've currently approached it:
A seperate repository, that runs and deploys playbooks (we define) against the latest HA version (or the one we specify) and deploys it on our Netlify hosting on a secondary host (e.g., screenshots.home-assistant.io or similar).
Docs can than just include those screenshots. Reason for a seperate subdomain / repo is to decouple the quite massive updates on the screenshots out of the documentation scope (we don't want to keep all these constantly changing screenshots in Git, it is a resulting artifact)
severe field
I would also like to discuss with you how we should handle screenshots and maybe define when to use them. Because for procedures, for example, they are redundant most of the times, since every step and interaction with UI is described.
orchid sluice
Agreed. Regular procedures don't benefit from screenshots showing the buttons if we can describe where they are
fossil fox
Agreed. Regular procedures don't benefit from screenshots showing the buttons if...
I disagree on that a lot actually.
If there is anything, I want our documentation to contain more visual guidance
Not just walls of text or procedures people have to closely follow
Being able to "see" what is written, help in many ways; for example, recognizing/confirmation you are in the right place while following along, but also, there is a large group of readers that scan over text that let them guide mostly by screenshots
severe field
In that case then, how do we decide that a step in a procedure needs a screenshot? How do we make sure that the screenshot we are not adding won´t be missed by the users?
Unless we want to add a screesnhot in every step, which will probably make the documentation heavy, boring and very hard to maintain and contribute to (which is something we should take special care of).
As a beginner, yes indeed, I have already felt the need of a visual clarification in many documentation parts (and not necessarily a screenshot), but not in procedures yet.
There, the issues I have identified are more related to: outdated info (such as incorrect UI strings), missing steps / actions, inconsistency in text style and formatting and long procedures that can be divided. So in my opinion, before starting to add screenshots, we should make sure that those issues do not happen and have lighter text that can be easily followed and scanned.