Try it now experience

[ghost]

There's a need to create an IDE plugin that will:

1. Open a right side panel (just like pull request panel) with nicely formatted text and action buttons that help a user learn new project/technology and IDE as well.

2. The plugin should use a descriptor file that defines content of the panel and actions tied to buttons.

3. The name of the descriptor file is walkme.json. A walkme.json is located in .che in the project root.

4. Format of a descriptor file:

{
  "title": "Guide title",
  "sections": [
    {
      "title": "Section #1 :: Simple",
      "text": "This section contains no action but some text"
    },
    {
      "title": "Section #2 :: Describes how to expand a path in the project explorer",
      "text": "To open a path the `expand-path` action is used. It requires the mandator `path` parameter containing relative to the project the path to open",
      "action": {
        "label": "Expand path",
        "actionId": "expand-path",
        "parameters": {
          "path": "src/main/java/org/jboss/as/quickstarts/kitchensink/service/MemberRegistration.java"
        }
      }
    },
    {
      "title": "Section #3 :: Describes how to open a file",
      "text": "To open a file the `open-file` action is used. It requires the mandatory `file` parameter containing relative to the project the file path to open . Also the auxiliary `line` parameter contains the line number to scroll when file is opened.",
      "action": {
        "label": "Open file",
        "actionId": "open-file",
        "parameters": {
          "file": "src/main/java/org/jboss/as/quickstarts/kitchensink/service/MemberRegistration.java",
          "line": 40
        }
      }
    },
    {
      "title": "Section #4 :: Describes how to run a command",
      "text": "To run a command the `run-command` action is used. It requires the mandatory `name` parameter containing the name of the existed command to run.",
      "action": {
        "label": "Run command",
        "actionId": "run-command",
        "parameters": {
          "name": "kitchen-sink:Build"
        }
      }
    }
  ]
}

In a nutshell, we need to define text elements (Subtitles, body) and buttons. All buttons will execute some actions. Actions can be simple IDE actions (like expanding project, opening wizards), executing commands by their IDs and opening files. The latter two will require attributes. A command should have a name or ID, while opening a file requires path, scroll to line and line(s) to be highlighted.

Once a user presses the button, an action is triggered. The plugin should be able to open files at particular position.

5. When a user selects a project in the project tree, the plugin looks for this file, and if found, right side panel becomes active and filled with content and buttons defined in the file.

6. It should be easy to customize json and see results in the ide - so, refreshing browser page or project explorer should make the plugin re-source the json and re-draw the panel.

7. Styles are not customizable in a json - in order to change styles, plugin and eventually assembly rebuild is required.

8. Right panel should be opened automatically when the IDE opens. Default width is to be discussed, but it should be reasonable enough to have space for the editor and at the same time make panel content readable.

Below is a very basic concept in a mockup.

[gorkem]

I think JSON is not a good format for this. Eclipse desktop IDE has a similar functionality which uses XML. The problem with formats such as XML or JSON is they are good for consuming on the software but they are not good for content creation. The ease of content creation is the most critical concern for this feature as we have seen from the experience on Eclipse IDE. I think we should rather use markdown or asciidoc for content for content for content.

Also the design should consider having multiple tutorials on a project. Right now it looks like this accommodates a single file or tutorial.

[benoitf]

asciidoc looks like the better way. Also rendering is supported on github.

[gorkem]

asciidoc probably fits better. @benoitf Is there a good tool chain we can utilize to do live preview on our editor for asciidoc?

[ghost]

Another alternative is markdown preview with embedded action buttons. This, however, makes the task a bit more difficult.

@gorkem @benoitf what do you think about the following?

1. We auto detect README.md and open it either in the editor in preview mode or in a separate tab.
2. We extend md syntax with action buttons syntax, maybe smth like (sure to be discussed and spec'ed out):

[action type=ide actionID=helpAboutAction]
[action type=openFile path=/path/to/file scroll=23 highlight=23:25]
[action type=command name=build and run]

3. We document this syntax and list of available actions, and users can reuse existing md and enhance them with action buttons if necessary.

We should also agree on different uses cases, like where to open the preview, wheather or not we do it automatically, what happens if there are multiple projects in a workspace, what happens to a multi module project with each module having own .md file etc.

[benoitf]

Asciidoc provides extensibility with macros while markdown is not (there are different markdown renderer so you don't know what you can use or not)
BTW Asciidoc can render default markdown as well so even if you write markdown syntax it should work.

about toolchain, Asciidoctor provides rendering with also binding in Java but in our case it's the javascript port that is interesting
https://github.com/asciidoctor/asciidoctor.js

An example of what we could do with live editing: https://espadrine.github.io/AsciiDocBox/

[ghost]

@benoitf yeah, I have read a bit about anciidoc - markdown syntax respected which is good. So, yes, it looks like this is smth to look at.

[slemeur]

We need to consider this issues in a bigger picture - not only for our specific needs but also consider how it could be interesting for anyone in the community. Guides and tutorials are a very important way to drive adoption of Che workspaces and growth of our community.

Format

Authoring and maintaining guides must be something simple and I agree the JSON format that is proposed at this moment will not be convenient. We had guided tours in the past but the format was really making them tricky to create 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 definitely 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, in the future, build a dedicated language server which would simplify the edition.

Multiple guides

There might be multiple guides provided for a single project and I agree that 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 project.

I believe that 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.

I would 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

I don't think using the right side panel is the right choice. I would rather use the editor area to display the guides.

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 default, we would open the guide in rendering mode.

By using the editor tabs 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.

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.

[ghost]

@slemeur agree on everything but not guides explorer. That's a) overkill b) takesmore time to implement. Otherwise, it's the vision that we have as well. Get rid of a tab and open in an edito in split mode.

[slemeur]

We first need to focus on:

• providing an editor tab with preview/edit switcher
• rendering of asciidoc files which must be fast enough for live editing (similar to the example provided by @benoitf : https://espadrine.github.io/AsciiDocBox/)
• define and implement our own macros

If you need to phase the requirements, there are two aspects which I believe can be added after those elements are in place:

1. Default open of readme.md and readme.asciidoc files for any projects
I don't think it's a big deal to implement, but you can remove that from the 1st step.

2. Multiple guides support
As far as we agree on the need that can be added later. But that would still mean that, we need to define accordingly:

• how guides will be store
• how we identify the default guide

[ghost]

I'd say ancii preview editor and own macros are two immediate goals. Live editing and multiple guides support are tasks to come after.

[gorkem]

@eivantsov +1 on iterating on the features. Can you create subtasks so that we can plan them separately?

[tolusha]

[tolusha]

Updated json format in the issue accordingly to what we have right now.