Bare with me for a moment while I shed some light š” on that.
I think itās fair to say software developers understand the importance of writing tests; Iāve certainly seen a great uptake in that in recent years š.Itās also fair to say up-to-date documentation would be very helpful on many levels: Developers ramp up quicker, non-developer co-workers understand the system better and most importantly, user-facing documentation (if written well and read by users) increases user satisfaction.
Write tests
To quote Guillermo Rauch:
Quite frankly, this used to be very time consuming. Times have changed and tools such as Cypress.io (https://www.cypress.io/) donāt over-promise by saying āFast, easy and reliable testing for anything that runs in a browser.ā
In this blog post, I am going to focus on Cypress.ioās video recording and how to leverage that. To learn more, I recommend https://docs.cypress.io/guides/guides/screenshots-and-videos.html#Videos.
Write documentation
Knowing how to write integration / end-to-end tests, letās focus on a currently still quite dark area (based on my experience): Documentation.
As developers, many of us like to build features, solve problems, deploy code, the list goes on. I have rarely seen āwrite documentationā listed in a pull request templateās task list, not to mention excitement on a peerās face when theyāre asked to write documentation š.
Again, thatās because itās time consuming and much more so than e2e tests, quickly becomes stale and with that, useless or confusing to the reader.
(If you do want to write and publish documentation, itās worth researching about https://docusaurus.io/).
So what if documentation could be automatically generated and kept in sync with the source code, hence the user interface in a web app would be 100% identical to whatās presented in the docsāāāalways š®!
Let the tests generate documentation
I recently started to spend some of my free time to contribute to https://github.com/withspectrum/spectrum in an effort to give back to a project I truly believe in and a product I recommend to friends and peers to connect with like-minded people in a number of online communities.
Spectrum uses Cypress.io for end-to-end tests. At the time of this writing, 104 tests exist and complete in roughly 15 minutes. Now, remember when I mentioned Cypress.ioās video recording feature above? Thatās enabled in Spectrumās code and after I ran the tests, I had a video file I can watch, pause, and resume to get a high-level overview of Spectrumās features.
For the first time in my career as software developer, I felt excited to jump into an existing code base!
Next: Generate user documentation
So far, we have:
- End-to-end tests for product features (both happy paths and error cases)
- A single 15 minute video that visualizes how to use the product features
So what do we need next in order to generate user documentation?
**Shorter videos, ideally one video per product feature.**In Spectrumās case: a video that shows how to register for an account or a video to explain how to join a community.The solution to that could be: The test code can use a naming convention for describe('', () => {})or it('', () => {})blocks to indicate which tests should run independently and hence create separate videos. Something along the lines of it('DOC: Register for an account', () => {}). A script then runs DOC: tests and copies the generated videos to aĀ ./docs/videos folder, where they can be referenced in an inline help feature in the web app.
**Crop the video to whatās important to users**A screenshot of a video generated by Cypress.io looks like this:
Screenshot of a video generated by Cypress.io e2eĀ tests
What we need for end user documentation is the web app itself, the part marked with a green rectangle. As a video, the steps described on the left execute in order, displaying the web app to the right.The solution to capture the green part is to either have a flag in Cypress.io or find a way to programmatically crop the video.
**Display the video as inline help**This part can be achieved by adding an inline help indicator (often a simpleĀ ?) next to product features a user hasnāt interacted with. Upon clicking thatĀ ?, the generated video on how to use that feature plays.
Conclusion
With Cypress.ioās video recording feature, a web app inline help system and a bit of glue code, I see a future where web developers focus on writing robust, well tested code and get bite-sized end user video documentation more or less for free.
Iāve been playing with that idea in my head for a few weeks. If anyone has some thoughts, please donāt hesitate to reach out.