5 ms·

Or IMHO this is much better solved with a literate programming approach where the tour content lives inside the code as comments. Then as code is refactored an

Or IMHO this is much better solved with a literate programming approach where the tour content lives inside the code as comments. Then as code is refactored and changed it's very obvious that the related docs and tour data has to change too.

the_duke 6y ago
Agreed. But many developers might be very much against littering code with such tour comments, and be very much opposed to any kind of responsibility of updating tours during refactoring. Me included.
lostintangent 6y ago
With CodeTour, you can have "content only steps" (introductories, interstitials), steps that speak to directories, and also, add steps to files that don't necessarily support comments (e.g. JSON). So there seemed to be some value in having the tour be more flexible, than what what might be achievable code comments alone. Additionally, after speaking with a bunch of folks, there are definitely teams that weren't interested in "polutting" their code with comments that might be tailored to onboarding new team members, and therefore, didn't need to be always visible. That said, I totally agree with the value of a literate programming-based solution. But there may also be some nice properties to a "side car" file as well, and so I'm primarily trying to explore how well we could make that work, in a resilient and easy-to-maintain way. We'll see how it goes!
- stareatgoats 6y ago
  > there are definitely teams that weren't interested in "polutting" their code with comments Add an extension feature that toggles (hides/shows) those comments maybe?
methyl 6y ago
Not an equivalent of literate programming. Here you can jump to arbitrary files at arbitrary points, in literate programming your code must flow from top to bottom linearly, which is most of the times impossible to achieve.
- qbasic_forever 6y ago
  No not with Knuth's original ideas for literate programming and cweb. There's an explicit abstraction between the location of prose and the final source code output and they can be woven in any way the author desires. You can even insert intermediate steps, like pseudocode that show building up the architecture in small incomplete steps, and all of that is removed entirely from the final source code result. It is actually quite complex and why more modern literate programming systems ditch it and basically turn into fancier comments.
  - methyl 6y ago
    Sure, I get your point, but this description stands in opposite to previous statement that “tour content lives inside the code as comments”. It seems to me that CodeTour is very close to Knuth’s idea.
    - qbasic_forever 6y ago
      I recommend reading up on cweb and its history. The tangling and weaving metadata and prose lives in the code with special fenced blocks. Noweb is a modern version of it: https://github.com/nrnrnr/noweb https://github.com/nrnrnr/noweb (but it's not really used or maintained much anymore)

the_duke 6y ago

Agreed. But many developers might be very much against littering code with such tour comments, and be very much opposed to any kind of responsibility of updating tours during refactoring. Me included.

lostintangent 6y ago

With CodeTour, you can have "content only steps" (introductories, interstitials), steps that speak to directories, and also, add steps to files that don't necessarily support comments (e.g. JSON). So there seemed to be some value in having the tour be more flexible, than what what might be achievable code comments alone. Additionally, after speaking with a bunch of folks, there are definitely teams that weren't interested in "polutting" their code with comments that might be tailored to onboarding new team members, and therefore, didn't need to be always visible. That said, I totally agree with the value of a literate programming-based solution. But there may also be some nice properties to a "side car" file as well, and so I'm primarily trying to explore how well we could make that work, in a resilient and easy-to-maintain way. We'll see how it goes!

stareatgoats 6y ago
> there are definitely teams that weren't interested in "polutting" their code with comments Add an extension feature that toggles (hides/shows) those comments maybe?

methyl 6y ago

Not an equivalent of literate programming. Here you can jump to arbitrary files at arbitrary points, in literate programming your code must flow from top to bottom linearly, which is most of the times impossible to achieve.

qbasic_forever 6y ago
No not with Knuth's original ideas for literate programming and cweb. There's an explicit abstraction between the location of prose and the final source code output and they can be woven in any way the author desires. You can even insert intermediate steps, like pseudocode that show building up the architecture in small incomplete steps, and all of that is removed entirely from the final source code result. It is actually quite complex and why more modern literate programming systems ditch it and basically turn into fancier comments.
- methyl 6y ago
  Sure, I get your point, but this description stands in opposite to previous statement that “tour content lives inside the code as comments”. It seems to me that CodeTour is very close to Knuth’s idea.
  - qbasic_forever 6y ago
    I recommend reading up on cweb and its history. The tangling and weaving metadata and prose lives in the code with special fenced blocks. Noweb is a modern version of it: https://github.com/nrnrnr/noweb https://github.com/nrnrnr/noweb (but it's not really used or maintained much anymore)