3 ms·

I meant a way to make up-to-date drafts: base it on an automatic execution trace, like from a debugger running the code. You get this 100% up-to-date trace for

I meant a way to make up-to-date drafts: base it on an automatic execution trace, like from a debugger running the code. You get this 100% up-to-date trace for free. It's crazy verbose, so apply filtering (e.g. to only key apis) to make it manageable. Then edit that draft manually. Like an annotated, abbreviated, step-into debugger. My thinking is that this makes it easier to get an initial draft. But maybe that basic trace is easy and natural to do manually? Also, I'm not sure how similar this "execution trace" would be to a tour based on explaining it... I suppose you could find out, by examining your best tours to see how closely they actually follow execution order (if at all). When I try to understand a codebase, I do trace calls manually, so there's probably some similarity.

lostintangent 7y ago
Ah OK cool, apologies for misunderstanding you. Now that I’ve got the core record/playback experience, I’m keen to explore ways to simplify the authoring and maintenance experience even further. Enabling a “code profiler” for recording/updating tours could definitely be really useful. Thanks for the feedback!
- hyperpallium 7y ago
  No worries, think your interpretation of just api calls is a good one, a bit like "tests as documentation". Could then have another tour for each module (api implementation). This approach would tend to confine the effect of changes (as in Parnas' On the Criteria To Be Used in Decomposing Systems into Modules https://www.win.tue.nl/~wstomv/edu/2ip30/references/criteria_for_modularization.pdf https://www.win.tue.nl/~wstomv/edu/2ip30/references/criteria...) Though multiplicity of tours is also complexity!