Improve the documentation

[fungiboletus]

• Up to date quick start
• Single place to find helpful resources
• More examples
• Document annotations (see Annotations (changes and documentation) #215)
• Explain more what ThingML is, can do, and what it can't do
• How to contribute documentation
• Syntax / keywords documentation
• Make a website ?
• Build an interactive tutorial that is actually cool, similar to tryruby or equivalent.

[brice-morin]

IMHO, we indeed need a website, acting as the single place to find helpful resources, documentation, getting started. I would suggest gh-pages. The README.md on the repo is just too messy, and I would only have info for developers on the master repo itself, not for users (who should use the website).

For the interactive tutorial, this is a good idea. A cheap version can be made quite easily (I guess), if we have the thingml compilers available somewhere in the cloud, + a way to run the generated code (packed in docker automatically generated from ThingML) on-demand. Well, actually not so cheap, maybe. A more fully-fledged version would need to use Language Server Protocol so as to get coloration, checks, etc. But I am not sure what support we get from XText there...

[fungiboletus]

Running the code on the cloud is a challenge because even though it's isolated in a container, it's still possible to mine whatever-coin-crap on cpu, run spambots, or worse. I would rather compile the code on the cloud using the javascript browser compiler, and execute it on the client's CPU. Or maybe the C compiler with an emscripten step.

For the editor, a web based editor such as monaco with the correct coloration should be fine. The ThingML DSL is not that crazy, if it's not possible to generate syntax coloration and light completion definitions, it's possible to write them by hand. It does look very easy to do.

In my wet dreams (figuratively) a visual state machine to debug would be so nice. The author of the state machine library has an example that I think we could get inspired from.

[brice-morin]

Yes, I agree with you. Generated JS code executed in the local browser is the way to go.

At some point we had a prototopye of grammar for Atom (which had limitations). So no, not impossible to make something similar in a web-IDE. But we should see what we can get for free, first.

As for the visual state machine, that is also a good idea. We have discussed something similar in the ENACT project, but I am not allowed to work on this project :-) @nicolasferry can probably inform you on this matter.

[fungiboletus]

If you find something that generates the grammar, sure. Personally I'm not planning to spend hours trying to find a tool to generate it, learn how to use, and debug it while it's so simple to do it by hand once in a while.

[brice-morin]

The good thing if we manage to have LSP up and running, is that it is a rather standard way, and then we can get a VSCode plugin "for free", for example.

See that for a XText/LSP/Monaco combo

[fungiboletus]

Neat. I would rather use such an editor than Eclipse to be honest.

[brice-morin]

Well, we can indeed expect the same limitations and the same benefits than the normal Eclipse plugin. With hopefully one single fix to implement to solve the problem in Eclipse and in the web editor. Of course, we need the LSP server running somewhere in the cloud, but we also need the ThingML compilers in the cloud... so not a big deal.

[fungiboletus]

Oh so it needs to run some Java/XText things server side ?

[brice-morin]

at least that is what I think, but I do not know much about LSP in practice...