Rewrite and refactor all documentation

[David-Else]

Here is the (current state of the) rewrite of the Helix documentation following the discussion at
#5428

• Improved readability, consistency, spelling, grammar, and best practices
  for software documentation
• Added missing information and expanded / rewrote sections
• Used triple tick sh for code blocks for text to be entered in the
  terminal
• Formatted Markdown to 80 chars using Prettier.
• Added some Table of Contents where I thought they were needed

This has been a huge undertaking, it is possible that I have made errors in the
parts I have re-written due to gaps in my knowledge, so I hope as many people as
possible can read it and confirm it is correct.

Please note, you can view Markdown diffs properly by clicking a button:
https://docs.github.com/en/repositories/working-with-files/using-files/working-with-non-code-files#rendering-differences-in-prose-documents

Another way to easily read it is to go to the Files Changed section with the diffs and click View File for each section:

TODO:

• Refine parts of this draft pull request, I am not 100% happy with all of it
• Fix the Windows section of Installing from source (waiting for feedback from @CptPotato)

NOTE: Part 2 to follow, splitting up and reorganizing the files into a better chapter structure.

[ayoub-benali]

Thanks for taking care of this @David-Else 🎉 I was about to add a section about the supported LSP features but since you reworking the doc I will wait until is merged.

I had in mind something similar to this page: https://github.com/sublimelsp/LSP/wiki/LSP-specification-implementation-status
Should I added to this PR ?

[David-Else]

@ayoub-benali That page sounds great, but I am not sure what to recommend at this stage. It could fit well in an appendices for reference. I need to get more feedback before I can think about adding more sections.

[CptPotato]

@David-Else I created a PR over at https://github.com/David-Else/helix/pull/1 adding the windows specific install section as we discussed.

[bindsdev]

I have a suggestion for the section on themes. The available themes for Helix are not very well documented. A start would be to document a list of all the available themes. In addition, a preview for each theme should be provided. This would make picking a theme much easier since the user would just have to go to the documentation, look for the theme they like, and set it in their configuration. This would prevent the potentially tedious work of cycling through every available theme with the :theme command, trying to find the one you like the best.

[archseer]

Themes: It's going to be a pain to maintain the list and the previews. You can already just tab through the list of themes and see the theme previewed live and with your preferred programming language snippet (surely pressing tab is no more tedious than loading a separate doc page and using the scroll wheel). I think this doesn't need to be a part of the docs.

[bindsdev]

Themes: It's going to be a pain to maintain the list and the previews. You can already just tab through the list of themes and see the theme previewed live and with your preferred programming language snippet (surely pressing tab is no more tedious than loading a separate doc page and using the scroll wheel). I think this doesn't need to be a part of the docs.

That seems fair. I understand and can agree that it could be a pain to maintain that as part of the docs. 👍

[cd-a]

Thanks for taking this on, @David-Else

[the-mikedavis]

I force-pushed a version without the formatting changes (no hard-wrapping at 80 and no changes to table layout) following up on #5545 (comment). You can compare the changes here. I also saved a version of the branch before pushing here. This is based on the latest master now as well.

I wrote down a few notes, I'll post those as review comments now.

[David-Else]

@archseer This has been my first time responding to a GitHub code review, should I always reply to suggestions or just hit resolved when I have completed them? I have been pressing the resolved button in cases where no comment was needed.

There is still the matter of title case in headings, you have corrected many of them to be lower case, shall I grep all the documentation and make sure all titles are lower-case (keeping things like proper nouns upper-case)?

There are still a few questions I left in the review comments to be answered, but other than that I think I have made all the corrections asked of me. The install page in particular looks really good now, so much better than it currently is on so many levels :)

[David-Else]

I have now done everything in the code reviews, anything more I need to do?

[the-mikedavis]

Just some minor comments/typos. Otherwise this looks good IMO

(I also merged in master since I've been merging docs changes that added conflicts. Hope it's not a bother!)

[archseer]

Thanks for working on this! Documentation really needed some maintenance and I think this will improve the initial experience for any new user 🎉

[cd-a]

Agree, this is great work. Thank you!