Explore using VS Code walkthroughs

[vinistock]

VS Code walkthroughs allow extensions to define a set of learning tasks with a lot of interactive functionality.

Explore if we can use walkthroughs for

• Feature discoverability and tutorials
• Ruby tips / learning

Might be something worth for Sorbet as well.

[andyw8]

I'm going to look into this for the Hackdays.

[andyw8]

Here are my notes, pasted from Logseq so please excuse the formatting:

---

• For the December 2022 Ruby DX Hackdays, I looked into Explore using VS Code walkthroughs.
• Initially I focused on the mechanics of building a walkthrough, but as I started to add the content, another area of interest emerged to me: How do we connect the terminology used by LSP specification to an end user's understanding of the features provided by the extension. I discuss both aspects below.

• Learning about Walkthoughs

• Exploring the Landscape

• I began by looking at the getting started sample as well some walkthroughs from extensions such as Gitlens.
• The majority of a walkthrough is built using simple markdown files, along with some configuration in package.json.
• Some limited forms of interactivity are available, such as:
  • Opening the extension's setting page.
  • Opening the command palette with some pre-populated text.
  • Conditionals such as if someone is using a Mac or Windows
• Content is typically brief, mostly consisting of one or two screenshots or short animations, with some short text.
• Walkthroughs are generally less than 10 steps. Some extensions, such as Gitlens, ship with multiple walkthroughs which help having a single long walkthrough.
• I wanted to see if there was a way we could show a walkthrough step only if someone was Shopify staff, but didn't manage to. This would be useful since it means we could bypass the version manager selection step (since it already defaults to shadowenv).
• Some Walkthroughs ship with separate versions of the images for light and dark themes.

• Building a Ruby LSP Walkthrough

• I built-up two walkthroughs:
  • An overview
  • A feature tour
• I structured the feature tour based on those listed on https://shopify.github.io/ruby-lsp/RubyLsp/Requests.html.
• I re-used the existing images, but there's work that could be done to clean them up.
• I ordered the walkthrough based on what I thought would be the most appealing/useful features first.
• I rephrased and renamed things in a way which would more understandable to the end user.
• One important thing the walkthrough should highlight is what's provided by ruby-lsp vs what's provided by the Sorbet extension.
• Since the walkthrough steps are markup, we could re-purpose those to build a 'marketing' site for Ruby LSP, and have the files shared to ensure consistency.
• I've opened a PR. It's minimal, but is almost shippable, if we wanted to use it as a starting point.

• Thinking about Terminology

• In the ruby-lsp README, we point people to https://shopify.github.io/ruby-lsp/RubyLsp/Requests.html to learn about the features available.
• The names we use derive from the LSP specification, and documentation seems generally aimed at a Ruby LSP developer, rather than an end user.
• The names given to features often aren't good indications of their purpose, for example:
  • Instead of mentioning RubyCop linting as a feature, it's called Diagnostics.
  • Instead of mentioning RuboCop auto-corrections, it's called CodeActions.
• Similar with the descriptions, an end user shouldn't need to know about the concept of an LSP Request.
• Even though our audience are developers, presenting documentation like an API reference is likely not the most effective approach.
• Documentation for ruby-lsp is understandably limited at the moment, but setting some conventions and guidelines now will help as we go forward.

• Establishing a Bounded Context

• Using the same vocabulary for developing ruby-lsp as for documenting it is not optimal.
• There is disconnect between the terminology that the LSP specification uses for features, and the terminology that a user would expect.
• Let's apply a concept from DDD: https://martinfowler.com/bliki/BoundedContext.html
• We can established two bounded contexts:
  • User-facing: Feature documentation, walkthroughs, configuration, UI and marketing
  • Internal-facing. The ruby-lsp implementation code, tests, and API docs.
• We should take care to pick names and terminology meaningful to end users, taking into consideration aspects such as:
  • That used by other Ruby tooling such as RubyMine
  • Conventions from the Ruby ecosystem
  • Conventions from other ecosystems, e.g. TypeScript
  • Language used within Shopify
  • Language used outside Shopify
• There needs to be a mapping, and it should be consistently applied across the User-facing context mentioned above.
• Some LSP terminology may map directly to an end-user feature. Others may be one-to-many or many-to-one.
• It's possible that may result in some user-facing terminology that is less precise than the LSP terminology. That may be an acceptable trade-off.
• For illustration, below are some possible mappings between the two contexts:

• LSP Terminology	End User Terminology
  DocumentSymbol	In-file Navigation
  DocumentLink	?
  Hover	Documentation Quick Lookup
  FoldingRanges	Code Folding
  SelectionRanges	Expand/Shrink Selection
  SemanticHighlighting	?
  Formatting	Auto-formatting
  OnTypeFormatting	Format As You Type
  Diagnostics	Linting (or RuboCop linting)
  CodeActions	Autocorrect (or RuboCop autocorrect)
  DocumentHighlight	?
  InlayHints	Inlay Hints (fine as is)

[andyw8]

Branch: https://github.com/Shopify/vscode-ruby-lsp/tree/andyw8/walkthrough