I guess navigation uses VS Code to locate functions etc, so it's robust to superficial changes (like ctags for vim).
Keeping docs in sync is a hard problem!... \tangent: maybe a tour draft, of execution trace of a typical use, filtered to only key api calls?
Would that satisfy what you’re thinking? Or were you thinking about being able to record a tour, and mark certain steps as being more important than others? Any feedback here is unbelievably valuable!
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.
Though multiplicity of tours is also complexity!