doc: Fix existing doc to promote che plugins and packaging with vscode extension rather than Theia plugins.

[sunix]

Is your task related to a problem? Please describe.

Currently in our documentation, we are referring to che-theia plugins or theia plugins. But Theia plugins are advanced concepts that we are using but community would not be interested into. Theia plugins concepts could go to contributing.md files where people would like to contribute to che-theia.
Community would rather be interested in VSCode extension + che.

Describe the solution you'd like

So my suggestion is that in our documentation we:

1. Replace any occurence of Che-theia plugins with Che plugins (that would be a VSCode ext packaged in a side car containers)
2. In the contributor guide, we shouldn't go through the creation of theia plugins but vscode extensions. Also it is not clear if a Che-theia plugin is a Che plugin or a Theia plugin. We should use only the 2 words in all our doc: Che plugin and VSCode extension. A Che plugin is a VSCode ext packaged in a sidecar container.
   

[mmorhun]

@sunix thank you for the proposal, but I am afraid calling VSCode extensions packed into sidecar container as Che plugins is not correct.
Starting from Che 7 we declare support for many IDEs. And if we talk about Che plugin we talk about something which works with Che independently from used IDE. Which is not true in your proposal. So, to me it leads to even more confusion: a user chooses an IDE, then adds a Che plugin and it doesn't work...
To avoid such situations we should clearly say, that VSCode extensions packed into sidecar container is a Che-Theia plugin or Che plugin for Che-Theia IDE. Which means that it is supposed to work only with Che-Theia.

[sunix]

Yes we have the ability to switch editors but the default would still be Theia. Theia will add another technology which people don't really care about. Like if we had to tell that it is a Che-theia-monaco-typescript plugin. Let's stick to what is the basics information and not adding too much informations that will confuse.

I guess there is a section about switching editors but this is a corner case. We could specify that vscode che plugins won't work in this case.

[mmorhun]

But one of the points is that Che users may easily switch editor from Che dashboard.
The story with Monaco in Theia is completely different: you cannot just replace it easily for something else without writing source code (I think a lot of it).

[sunix]

Maybe some user would try it. But they would just try it not use it for coding. But finally most of our users will use che-theia for coding.

[sunix]

And i don't see how saying that it is a Che-theia plugin and not a Che plugin will help them to understand that the could run a VSCode extension or not.

[mmorhun]

Probably most of the users will choose Che Theia as IDE, but I think we'll have users who use different IDE as well.
As about VS Code extensions: docs should say, that a VS Code extension may be packed as Che Theia plugin.

[sunix]

Most people won't choose, they would just use Theia but won't know what is Theia. They are not interested into it.

The doc should say "VSCode extension + side car containers" and we should avoid introducing other technologies to these concepts. Che plugins is the best option to avoid user to be confused with the Theia plugins or Theia extensions which have nothing to do with a vscode extension + sidecar containers.

Frankly speaking, some users are already confused, this issue is not coming from no where. So please don't use Che-theia plugins at all, anywhere.

Also, your che plugin could work not only on Theia. Theia is the tool that runs our vscode ext at the moment. But, as you say, we could switch editor so it could be another editor that would consume vscode ext + sidecar containers

[mmorhun]

To me we shouldn't put into docs things which is not completely true. It will lead to confusion and probably bad reaction from people who decide to sort it out (which is not complicated). At the end, our users are developers and I believe it won't be hard for them to understand (and know name of the editor in which they are working).

[sunix]

what is true is that vscode extension + side car container is not specific to theia. you could run them with theia but it could be another runtime. So what is the confusion ?

[monaka]

I guess it can be resolved by putting more layers.
Like:

• Contributing Guide
  • Che-Theia
    • Developing Plug-ins
      • @theia/plugin
      • sidecar container with vscode-ext
  • GWT-IDE (... if supported in someday)
  • ANOTHER_IDE (... not known yet)

[monaka]

@sunix Indeed the another IDE also may use sidecar containers. So, how about this?

• Contributing Guide
  • Che-Theia
    • Developing Che-Theia plug-ins
  • sidecar container with vscode-ext

[sunix]

@monaka For the moment, I would move doc related to theia plugins to CONTRIBUTING.md of che-theia. I don't see any people, except the Che committers, writting a "che-theia plugins"

But if we have more people interested in writting theia plugins in the future, we could move that to the main documentation as you suggested. What I would like is to have the best documentation for the right people and being agile and change it if it has too.

[monaka]

@sunix Just based on my experience, potential uses who want to develop che-plugin are not only Che committers. Some users will customize che-theia for their purpose. For example, I extended my graphical editor to che-theia. And I won't merge it to eclipse/che-theia as it isn't for general purpose.

[monaka]

The title "Contributing Guide" may not fit to the contents. It's better to "Extending Che" or something.

[sunix]

@monaka I understand. Let's summarise: now we have several extension points:

• VSCode extension (with or without sidecar container)
  Works on vscode and Che. This is the prefered way. it can be activated from a devfile and be included in a plugin registry.
• Theia plugin (with or without sidecar container)
  Basically the same as vscode extensions. But we use Theia plugins when we need to interact with Che API at the moment. This is the only difference we have in general. If it is not the case, it is mostly because of historical reasons and we haven't had time to rework these parts.
• Theia extension.
  When it is not possible to extend things with vscode extensions or theia plugins. We use that kind of extension mostly to access to Theia internals or when the API is not enough to do what we want.

In the last case, you may not contribute to Che-theia but you will kind of fork it to make your own Che-theia. We offer that possibility but it is not the preferred way. Maybe it makes sense to have that part in our documentation but i would put that to an advanced section. For now, for most of our contributors that would contribute to our registry to extends their workspace, the prefered way is vscode ext + sidecar container. I would like to make that clear for people who read the doc and not confuse them with Theia's plugin or extensions.

We can talk about all the possible extension points as an introduction but we should promote how to write vscode extension + sidecar container in our doc.

We could create a Customizing Che-Theia section where we explain how to write theia plugin, interact with Che API and talk about theia extension and che theia packaging. That could go in the README of che-theia or in a advanced section of the documentation. But definitely not the primary way to extend Che to add IDE features.

Regarding the title. I was thinking the same but then ... is someone who is contributing to our plugin registry a contributor of Che ? I would say yes but I know it is confusing. Extending Che: add IDE features.

[monaka]

I agree the topic vscode extension + sidecar container should be the top of contents. It will be the most demanding item from users. There is no room for doubt.

Next, Theia plugin (with or without sidecar container) and Theia extension. should be included or not.
Basically, I prefer the official document is centralized.
At the same, I can follow the opinion "topics about Che-theia should be separated from Che document" since Che-theia is just a IDE-plugin for Che.

Even if topics were separated, It's better to add a short description and links to Theia plugin and Theia extension
"Extensible" is a major advantage over other IDEs. Readers will feel some more charm to Che.

I'm easy about the title.
Just I guess many users don't send pull-request after they deployed their patched plugin repositories.
I feel Extending Che: add IDE features. nice.

[sunix]

We could have a new section next (before) to the Che-theia plugins one:

• Developing VSCode extensions in Che

[themr0c]

@rkratky That's something we should take into account while working on the outline.

[themr0c]

This issue is also tracked here: https://issues.redhat.com/browse/RHDEVDOCS-1579

[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.

[ericwill]

I think this is covered in the docs now, as well as with: eclipse-che/che-docs#1917