themmes
commented
4 years ago @lostintangent Thanks for spinning up a new thread, sorry if I unnecessarily cluttered your Github integration thread with this suggestion.
I think your downsides make a lot of sense, though for the discussion I would like to present a different perspective:
-
I think there is three parts to the tour:
codetour instruction,comments/explanationandcode. In general I believe it is considered good practice to comment with your code. Currently, the codetour stores the explanation/comments with the tour, not with the code, right? Once you keep your comments with your code it will become fairly easy to switch between keeping the codetour instructions in a separate jSON or as comments in your code. On top of that I think labeling the codetour instructions as obtrusive ignores the potential added value they have outside of the tour. Much like spotting a roadsign without walking the entire route... -
Why is it you would like to annotate data files? Isnt it the purpose of the tour to guide you through a codebase where the logic of code may at first not be obvious to the developer? I think, but I might be wrong, that for every data file there is a point in the code where its loaded. That might be the best location to create a tour step.
-
I agree, though you could solve that by just continuous numbering and play parts, instead of having multiple numberings
-
I personally think that for codetour to become a common thing, it should not rely on any visual editor or be coupled with a specific IDE. However, without the visual editor the process of creating the tour in a separate file might be too much work.
Let me know what you think!
lostintangent
Currently, tours are persisted as JSON files and written to the “.tours” directory of your repo. However, we could also explore allowing tours to be defined via actual code comments. For example, the following could represent a step definition above a line of code:
While this approach could help mitigate tour decay, it also has some potential downsides:
The comments would clutter the code for everyone that’s reading it, as opposed to enriching the code for only those that are actively taking the associated tour. This might not be a big deal, but in order to achieve long-term traction, I can’t help but feel like being unobtrusive has value. The “side car annotations” approach helps with this, and so it just comes down to the trade offs that teams are willing to make, and how well I can address bit rot by associating the tour with a specific commit/tag. I’m also exploring ways to notify you when a tour should be updated, but that’s a little experimental right now 😁
I want the tour to be able to span all file types, and I’m not sure if the comment-driven approach would naturally work in 100% of meaningful scenarios. For example, how would you define a step in a JSON file (since it doesn’t support comments)? Since the role that declarative code/metadata plays in codebases can be a huge source of confusion, I felt like we needed a solution that was fully agnostic to the grammar of any specific file type.
A codebase can define n-number of tours, and therefore, a single line of code could actually participate in multiple different tours. Having a single line annotated with two (or more) different tour descriptions could amplify amplify the potential for clutter.
The tour would no longer be defined in a single place, and therefore, the benefits of having a human-readable file for quick/easy editing would decrease a little bit. In general, I want the visual editor/recorder to enable easy tour authoring for most scenarios. However, as with any abstraction, there’s commonly value in being able to pierce it for advanced tasks.
You wouldn’t have a natural way to annotate folders or create “content-only” steps (e.g. intro instructions), both of which have come up as being valuable for folks using CodeTour.