Guided Flows and Tutorials in Che

[slemeur]

Goals

The main goal of this issue is to allow the creation and the authoring of technology guides and tutorials by using Che.

Targeted users:

• Technology provider: Someone (or a group) who is providing a technology such as a language, a framework, a library or an application
• Technology adopter: Someone who is looking at a technology, to discover it, learn it and use it.

For any technology provider, there is a need to onboard technology adopters as fast as possible - so the technology adopters can understand the value of the technology and start leveraging it. In general, this is covered by a set of documentation, guides and tutorials which are requiring installation and setup of a developer workspace.

With Che, it is possible to pre configure a developer workspace with the proper stacks and dependencies for the technology, to pre configure a set of commands that can be used, to pre configure sample codes or bootstrappers - which makes the on-boarding experience simpler and remove the setup of the developer workspace in the sense of traditional IDEs.

Once the developer workspace is setup, a technology adopter should be able to learn the technology with guided tours and tutorials to be displayed within the IDE, so he can follow instructions provided by the technology provider.

Technology providers will author guides and tutorials and will be able to provide links to an hosted Che version where the adopters will be able to run those guides. This is a way to drive adoption of Che workspaces and growth of our community.

Details

Format

Authoring and maintaining guides must be something simple and the JSON format that we used in the past for the guided tours was really making them tricky to create, author and maintain.

A guide/tutorial can contain different kind of content (not exhaustively listed here):

• textual explanations
• actions
• images
• code snippets

On those elements some specific formatting could be defined. For example, in the body, a tutorial might use a bulleted list. So we need to address those needs as well.

Considering markdown/asciidoc formats are going to provide what we need. Using that format would also allow us to leverage readme.md or readme.asciidoc which are provided on many repositories.

Actions

Actions would be provided as macros inside of the guides.

We already have actions defined in multiple places: factories and Chefile. We need to carefully think about using a consistent format to define the macros.

To make it easier to create the guides, we could build a dedicated language server which would simplify the edition.

Multiple guides

There might be multiple guides provided for a single project and it is important to take that into consideration now as it would impact the end-user experiences. The guides could be accessed when the user is using a "Try it now" button, but they should also be available at any point in time.

There could be different guides, for different areas, for "getting started" indeed but there could be guides for more advanced/sophisticated information which the developer will progressively dig in after few hours of work on the technology.

The guides could be provided inside of a .che folder as a set of asciidoc/mardown files. As there might be multiple guides provided, we need to mark/indicate which guide will be the default one.

We could provide a guides explorer, as a left panel, along with the other explorers that we are providing. This way, we can provided a unified and consistent user experience.

Quick mockup:

End-user experiences

1. Loading default guides by default

This is a great opportunity to improve the empty state in the IDE. The first time a workspace is opened with a project, we will open the default guide.

• If the project is providing guides, we will bring the default one.
• If the project is not providing guides, but having a readme.md or readme.asciidoc, we will display it by default.
• Otherwise, we'll keep the current state.

2. Guide window

We should use the editor area to display the guides directly. There will be two modes to open a Guide:

• Rendering mode
• Editing mode

We will provide a switcher so that it's possible to go from one mode into the other one. (Similarly to how github is handling the edition of markdown file).

The basic requirements here is to provide a convenient editor for markdown/asciidoc files, which allow edition and preview.

By using tabs from the editor area to do that, there will be a lot of benefits:

• User can split editor panes and organize the layout exactly the way he wants. He could display the guide on the left/right side by side with the code or other IDE elements.
• User could open a guide in two different tabs, split the panes and display the two different modes (editing/rendering) side by side. This would make the edition and the turn around on the guides really convenient.
• We don't invent any UX, we reuse what we already have in place and which users are easily understanding.

By default, we would open a guide in rendering mode.

3. UI

For consistency and integrated experience, we will reuse the UI components and different styles we already have in the IDE. We will apply the theme that is selected by the user.

This will also make it easier for anyone (who might not have CSS skills) to get a guide properly rendered in the layout, without having to provide any particular efforts.

Sub tasks

• Define format for writing guides Define format for writing guides #6292
• Guides panel Add guides panel #6295
• Guides rendering Guides rendering in the guide panel #6296
• Extend guide render to display and execute che actions Extend guide render to display and execute che actions #6297
• Rendering/Edit mode for guides Rendering/Edit modes for guides #6299
• Basic autocompletion for actions in edit mode Add autocompletion for che actions in edit mode #6302
• Guides explorer Guides explorer #6303
• Language Server
• Add action to highlight a specific excerpt of code in the editor -
  Add action to highlight a specific excerpt of code in the editor #6333
• Scrolled line should appear in the middle of the editor -
  Scrolled line should appear in the middle of the editor #6330

[tolusha]

Try it now experience: codenvy/redhat#30

[garagatyi]

Considering markdown/asciidoc formats are going to provide what we need. Using that format would also allow us to leverage readme.md or readme.asciidoc which are provided on many repositories.

I think it is very tricky and error prone to parse something that is not machine-friendly. So, we may get a lot of nasty bugs if we decided to go in this direction.

To make it easier to create the guides, we could build a dedicated language server which would simplify the edition.

Instead of parsing MD files we can use some JSON or YAML format and LS to build it.

We can use guides in Che usage documentation and release notes. User clicks a link and his IDE starts guide. We would need to create a way to choose where a user wants to use the guide. It may be SaaS packaging of Che, OnPrem or even user's own local Che.
We should consider the creation of dependencies system in the guides, so when a user starts a guide we check whether the user has all needed plugins, versions to use that guide.

[che-bot]

Issues go stale after 180 days of inactivity. lifecycle/stale issues rot after an additional 7 days of inactivity and eventually close.

Mark the issue as fresh with /remove-lifecycle stale in a new comment.

If this issue is safe to close now please do so.

Moderators: Add lifecycle/frozen label to avoid stale mode.

[gorkem]

Reopening the issue to be reused for Che 7

[gorkem]

Here is a vscode extension that can be used for this https://github.com/redhat-developer/vscode-didact

[che-bot]

Issues go stale after 180 days of inactivity. lifecycle/stale issues rot after an additional 7 days of inactivity and eventually close.

Mark the issue as fresh with /remove-lifecycle stale in a new comment.

If this issue is safe to close now please do so.

Moderators: Add lifecycle/frozen label to avoid stale mode.

[pwright]

is this out of scope,or should it be reopened?

[ericwill]

All the dependent issues here are done, I'd say let's leave this closed and open a new issue for anything left.