4 ms·

>Docs should be tested - because you may be sure that everything is right, but without real users, like with any other product, you won't know for certain. Test

>Docs should be tested - because you may be sure that everything is right, but without real users, like with any other product, you won't know for certain. Test it and test it again. If you want to automate this, see: https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory It is not a common approach, but generating how-to docs from tests can be almost unreasonably effective.

ramon156 3y ago
Kind of a bummer when the first thing you see is master pipelines failing
rudasn 3y ago
I'd love to learn more about your experience on doc gen from tests. A few years ago I wrote a js lib that would read pupetteer - like commands and generate screenshots and videos of the sessions. So you'd define a feature, a js file with commands like navigate To, click, etc, but with the added options of adding annotations (tool tips) and borders to elements on the page. The loaded page would also have a proxy cursor that would move nicely towards the element to be clicked, focused etc. The end results are videos and screenshots that look like they have been made manually, but with no voice or audio, just interactions. The speed was slowed down as well to make them easy to follow along. Then it would diff the screenshots with cached ones and discard if the changes were minimal (eg. timestamps). I think I also did some markdown parsing as well, so that you'd write something like `feature:x step:5` in your markdown docs and it would replace it with the correct html to load the screenshot and/or video. I really liked the end result, but having to write test-like code to generate screenshots and videos looked a bit weird. I didnt end up using it, but it's something I think about from time to time.
- hitchstory 3y ago
  I've actually just been creating step by step markdown docs with screenshots with this approach but I love your idea of embedding annotations in videos with JS popups and a proxy cursor. Assuming playwright allows for it, I will experiment with this. My experience has been that customers are usually just happy to get docs that are guaranteed up to date even if they're not very good. They seem receptive to the idea of writing YAML that generates this stuff too. I think I might blow some minds if I combine this with your popups and maybe some AI generated voiceovers.

ramon156 3y ago

Kind of a bummer when the first thing you see is master pipelines failing

rudasn 3y ago

I'd love to learn more about your experience on doc gen from tests. A few years ago I wrote a js lib that would read pupetteer - like commands and generate screenshots and videos of the sessions. So you'd define a feature, a js file with commands like navigate To, click, etc, but with the added options of adding annotations (tool tips) and borders to elements on the page. The loaded page would also have a proxy cursor that would move nicely towards the element to be clicked, focused etc. The end results are videos and screenshots that look like they have been made manually, but with no voice or audio, just interactions. The speed was slowed down as well to make them easy to follow along. Then it would diff the screenshots with cached ones and discard if the changes were minimal (eg. timestamps). I think I also did some markdown parsing as well, so that you'd write something like `feature:x step:5` in your markdown docs and it would replace it with the correct html to load the screenshot and/or video. I really liked the end result, but having to write test-like code to generate screenshots and videos looked a bit weird. I didnt end up using it, but it's something I think about from time to time.

hitchstory 3y ago
I've actually just been creating step by step markdown docs with screenshots with this approach but I love your idea of embedding annotations in videos with JS popups and a proxy cursor. Assuming playwright allows for it, I will experiment with this. My experience has been that customers are usually just happy to get docs that are guaranteed up to date even if they're not very good. They seem receptive to the idea of writing YAML that generates this stuff too. I think I might blow some minds if I combine this with your popups and maybe some AI generated voiceovers.