Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [lsp4e-dev] LSP4E Docs


On Mon, Jan 29, 2018 at 9:07 AM, Patrik Suzzi <psuzzi@xxxxxxxxx> wrote:
The doc folder could be a standalone mvn project, only to generate the documents to be linked to the LSP4E project page.
The effort should be minimal, given there are already asciidoc maven plugins available [#1].

I agree it would be minimal, but I still question whether it's worth it:
* First, it's not so minimal because it requires to consider where to pushthe generated docs, how to version them and so on.
* Then, I believe the audience of LSP4E (plugin integrations) are mostly comfortable reading .adoc file directly without need to render it automatically anywhere. Note that the Eclipse IDE has support for adoc rendering for people who have the .adoc files.

Renaming is not important, but to build the mvn project, its name should be structured. Anyway, if this is not needed we can just stick to have asciidoc documentation with no doc generation.

I find it's more valuable to focus on the content of the documentation first than to focus on generating a website from it.

In the documentation will be clear that you can have you language server built with any technology you want i.e. as Microsoft describes [#2], Xtext, or other.

The documentation of LSP4E should not explain what is a language server. Knowing what a language server is and how diverse they can be is expected to be a pre-requisites for users of LSP4E. The only and best thing we should do is to link to https://microsoft.github.io/language-server-protocol/ in intro with a very few punchline arguments that will convince people who don't know what a LS is yet to click the link and learn there.

As first example, I will add the xtext one. Then, when I find time, if this is a valuable idea, I could present also other options.
Indeed, it is clear the target audience are the people who want to develop LSP4E, and I think presenting concrete cases of integrating a LS in Eclipse could increase the interest in the project. 

I agree that case-studies of integrations can be the most interesting documentation for our target audience. We could start by listing all known integrations and ask for their authors to add some technical notes about the LSP4E part in documentation.

Cheers,

Back to the top