Documentation strategy

[vhemery]

Hello,
I'd like to ask what is the (user-accessible) documentation strategy on EMF.cloud and whether we should upgrade it.
GLSP and JSON Forms have their own websites, hence their own documentation and that's perfectly fine with me.

My concern is more about how we provide a structured technical documentation for developers who want to dive deep into the technology (either in the umbrella project website or for each project website individually).
There is a README.md with technical documentation in each project, but that does not leave a lot of room for structured content and it is not the most user-friendly way to show it. If I add too many details in the emfcloud-modelserver README (like how to customize Codecs or the Model Watcher I'm working on), I'm afraid the README may become too fat and impossible to read.

An example I like very much and have found very usefull with experience is the Xtext documentation:
https://www.eclipse.org/Xtext/documentation/index.html
It is accessible, well structured and easy to navigate.
There is even this nice "Edit on Github" button which encourages contributing.

Would you think it will be possible to have something similar in the https://www.eclipse.org/emfcloud/documentation/ website?
Would it be possible to have the umbrella website look for documentation content from each of the individual project repository?

IMHO this would make much easier to share common recipes hidden in the code and user-recipes we might not think of.

Thanks for your views on this matter.

[Edit]
By the way, I just noticed that the "Additionally, please see this talk introducing EMF.cloud at EclipseCon 2019" link points to a non-shared google doc presentation... Maybe it's best to point at https://www.youtube.com/watch?v=ezX0DIeR3ek instead.
[/Edit]

[martin-fleck-at]

I agree with you that the documentation should definitely be improved and made available in more than just READMEs. So thank you for raising that and we will provide something hopefully soon.