Web documentation part outdated

[theogiraudet]

Hey!

I am currently teaching Langium to students in an MDE course.
During this course, the students have to simulate a robot in a webpage.
For that, we are sharing to the student these two pages, respectively to set up the web part, then the notification system:

• https://langium.org/docs/learn/minilogo/langium_and_monaco/
• https://langium.org/docs/learn/minilogo/generation_in_the_web/

However, I have the impression that the pages are not up-to-date for this part.
Indeed, since some versions, Langium Generator directly generates all the required artifacts concerning the initialisation of the web server and client.
As a result, the first page, which is a prerequisite of the second one, looks obsolete (not needed + mentioned files not existing anymore).
Moreover, the second page seems also out-to-date or at least, may not be enough to fully understand.
In the "Listening for Notifications in the Client" section, the file with the wrapper must be modified to listen the notification.
Since the first page is outdated, this may be difficult to identify which files to edit. As far as I know, this is setupClassic.ts or setupExtended.ts, but I don't know if this is the best way to do with the latest version of Langium.
Thanks!

[msujew]

Hey @theogiraudet,

during the past few years since the tutorials about Langium in the browser were written, quite a lot happened in the area of the monaco-languageclient library. In fact, the library changes so rapidly that we recently decided in a dev-meeting that we probably will no longer provide specific tutorials for that, as that is unmaintainable for us to the standard that we want. Instead, we plan to link to the Langium integration example of the monaco-languageclient. It will be always up to date and provide better help than we can in this repo.

I know that this makes writing a web based language client more difficult as it fragments the parts you need to learn about, however, we want to keep the Langium documentation specific to the framework and not branch out too much to all the possible language clients.

[theogiraudet]

I understand, thanks for the answer!

[kaisalmen]

Hi @theogiraudet this doesn't mean that the tutorials will disappear. I will analyse what we could integrate into the monaco-languageclient repository directly and how you could bootstrap a Langium project from there. We already have the Statemachine example, Langium grammar (extended) and Langium grammar (classic) integrated, but there is no tutorial how to achieve it. If we move the existing tutorials over there, we can also align it more easily with the changes happening in the web space.

[theogiraudet]

Thank you very much for your answer, it would be much appreciated.
As part of my course, I had to document this myself for the students, but as I will soon no longer be at the university, it may be difficult for my successors to maintain it afterward.
I don't know if this would be relevant, but perhaps a banner could be added to the current documentation page to warn other users that this page is obsolete.

[montymxb]

I would agree that adding some banner at the top would be a good solution here. It would specifically be nice to point out the versions that are stated at the top, but revise the text to inform the user these are the last supported versions for this documentation (rather than implying future versions will work as well).