How can you make sure that the walkthroughs are in sync with the code? Especially across repositories. The article is surprisingly light about this.
It kinda reminds me of the rust doc and doctests (snippets in the docs that are valid rust and are run as part of the tests), but across several files/repositories. They can be used to show a pattern, although usually a local one.
mentioning the release version that a walkthrough was written for is not a perfect solution, but it saves a lot of time when trying to figure out why a certain step does not work anymore
if the source is available, hardlinks to specific lines in a specific version would be pretty good
I'm not very optimistic about this type of features. I mean I like them, I think it's a step forward and everything BUT most projects hardly even sync comments with the code in the same branch, two lines down. And the amount of tickets pointing to lines of code in the tip of main instead of a commit hash is just one example of drifting 'truths' that nobody cares enough to sync.
I wouldn't expect this to be considered a first-class documentation task and have someone actively maintain it when code velocity often outpaces documentation. I mean if you refactor something now you also refactor the walkthrough? Ugh.. nobody got time for that.
What I'd like to see is some profiler or something auto-generating walkthroughs based on the 'beaten path' of the business logic, starting from the entry points of the.. thing, for each release.
3 comments
[ 3.5 ms ] story [ 11.7 ms ] threadIt kinda reminds me of the rust doc and doctests (snippets in the docs that are valid rust and are run as part of the tests), but across several files/repositories. They can be used to show a pattern, although usually a local one.
if the source is available, hardlinks to specific lines in a specific version would be pretty good
I wouldn't expect this to be considered a first-class documentation task and have someone actively maintain it when code velocity often outpaces documentation. I mean if you refactor something now you also refactor the walkthrough? Ugh.. nobody got time for that.
What I'd like to see is some profiler or something auto-generating walkthroughs based on the 'beaten path' of the business logic, starting from the entry points of the.. thing, for each release.