Lsp-mode: Readme and wiki pages

[brotzeit]

We already discussed this in our gitter channel, but I think it would be good to have an issue for this topic. How should we structure our documentation ?

[yyoncho]

I will list the things that we probably do not want to change:

1. The external packages (e. g. lsp-java/lsp-python-ms, etc) are documented in their own readme.
2. lsp-mode's readme contains general information about lsp-mode.

The open question are:

1. Where do we document the properties of language servers integrations that are part of lsp-mode package?
2. Where do we put the guides on how to setup the language server(and related info) about each of the LS that are part of lsp-mode?
3.

The options are:

1. Use wikis linked from the readme.
2. Use lsp-mode's readme.
3. Use standalone doc files in lsp-mode repo(same as wikis but have the docs in source code)
4. Create standalone docs website or use https://readthedocs.org/ or equivalent.
5. Other suggestions?

[danielmartin]

I would organize the README with a focus on programming languages. The TOC should show a list of supported languages to go to information about how to setup that particular language in lsp-mode. That's what most first users would like to do when they find this project; now that information is a little bit buried in a table (the README is already very long). Ideally a use-package code snippet they could copy and paste in their initialization file.

Configuration details, debugging info, etc. could go to a secondary Org file. I don't personally like GitHub Wikis, they are not very discoverable or searchable.

Documentation about configuration options may be generated automatically from the Elisp files. There are some packages that do that, but I have no experience with them.

[brotzeit]

Documentation about configuration options may be generated automatically from the Elisp files. There are some packages that do that, but I have no experience with them.

I think I would prefer this solution. However we still need the possibility to add docs manually.

[yyoncho]

We have a decision here - we will gh-pages and @ericdallo is working on that

[ericdallo]

Good idea document here our decisions :clap:
I agree with @danielmartin about the wiki, It's not very searchable, not very customizable and no options for SEO.

IMO, I think that we should have something like a great landing page for new users, like here and tune the SEO metrics(we also can add a Google Analytics to see how the users are navigating through the pages :eyes: )

I like the idea of linking all about Emacs LSP in this page, like here:

And I like the idea of generating the configuration options from .el files too, and I can study how to implement this.

[ericdallo]

About the README too long, I agree with that and can suggest we separate into other files similar to how doom-emacs does.
With this, we can organize our webpage's navigation structure to navigate to each of these files

[danielmartin]

We could have a "Languages" section in the left menu, with an entry for every supported programming language. That would reduce the size of the README because for some languages we have a lot of available configuration settings that would be moved to the corresponding language page (e.g. Rust, or Scala).

[ericdallo]

Yes!
@yyoncho gave exactly that suggestion too on Gitter :)
I'll work on it

[ericdallo]

Code generation for custom configurations done :)
https://emacs-lsp.github.io/lsp-mode