Rewrite and refactor all documentation

[David-Else]

Here is the (current state of the) rewrite of the Helix documentation following the discussion at https://github.com/helix-editor/helix/discussions/5428

• [x] Improved readability, consistency, spelling, grammar, and best practices for software documentation
• [x] Added missing information and expanded / rewrote sections
• [x] Used triple tick sh for code blocks for text to be entered in the terminal
• [x] Formatted Markdown to 80 chars using Prettier.
• [x] 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
• [ ] Write overview
• [ ] Write other sections following discussion
• [x] Fix the Windows section of Installing from source (waiting for feedback from @CptPotato)
• [ ] Fix the Migrating from Vim section and integrate it (merge in the WIKI article?)
• [ ] Reorganize all the documentation into something like the proposed layout below
• [ ] Confirm the format is OK to create the mdBook

I believe it all now requires reorganization, and I have created a draft layout as follows. What are the maintainers' thoughts on this?

Introduction

• Overview
• Installing Helix

Getting Started

• Familiarizing yourself with the basic navigation and interface

  • Navigating using Tree-Sitter Textobjects
  • Selecting text using Textobjects
  • Moving the selection using Syntax-Tree Motions
  • Storing text and data in registers
  • Selecting and manipulating surrounding characters

• Customizing the editor's settings

  • Configuring settings
  • Remapping keys
  • Configuring language settings
  • Configuring the language server
  • Configuring the Tree-Sitter grammar

Basic Editing

• Mastering the Keyboard Shortcuts and Navigation
• Learning the commands
• Formatting your code
• Searching and replacing with ease

Advanced Features

• Creating your own theme
• Integrating with version control
• Adding Languages
• Adding Textobject Queries
• Adding Indent Queries
• Finding additional resources (e.g. online tutorials, user forums)

@pascalkuthe What do you think about Advanced Features/Integrating with version control documentation? It would be good to mention the Git Gutters and their current limitations. Would you like to write something and I could re-jig it to fit the style of the rest of the docs?

I have yet to write an overview section. It should explain what Helix is, include the logo, and serve a similar purpose as the README. The documentation should be able to stand alone from the README, even if there is some duplication in the overview.

Do we need a Guides section, it seems a little strange as all the docs are a guide? Could the current content be added to Advanced Features?

How about integrating the migrating from vim into Familiarizing yourself with the basic navigation and interface section?

There are a couple of essential topics missing from the documentation, such as Formatting your code and Searching and replacing with ease, that I believe need their own section, even if they are brief. All the essential topics for a new user should be included in the table of contents for easy access.

[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 https://github.com/helix-editor/helix/pull/5545#issuecomment-1399323148. 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]

@the-mikedavis I don't really understand what you did when you force pushed your formatting fixes, but I think I have undone it somehow :( When I applied the first code review fixes from the GitHub CLI it worked, but as soon as I pushed from my branch everything went wrong and it somehow reverted back to the wrong formatting and added back loads of old commits?!

I thought I had pulled in your changes and was just going to push them up again, I have no idea what happened. I know it is not your job to educate people about how to use git, so I really apologise for my ignorance in this. I tried to revert the last commit that caused all the problems, but it didn't fix anything. Please can you get me back to how it was before the last commit that I tried to revert and tell me how I can continue to work on this from my local computer? Thanks!

[the-mikedavis]

Ah no worries, I think I still have the branch locally so I might be able to force-push it back or it might work to drop the merge commits.

When pulling a branch that was force-pushed, you can git reset --hard remote-name/branch-name to discard your local branch and use the remote one. For example I have my fork setup as the origin remote and I force-push my driver branch to that remote often. So when I use another machine that has an old version I use git checkout driver and git reset --hard origin/driver to use the latest driver branch pushed to github. I don't think there's a lazygit helper for this - that would be a nice custom commnad

[the-mikedavis]

Ok it looks like this only needed a revert of the merge commit in 7c84042 so no need to git reset --hard for this change, you should only need to pull this time. I also merged in master

[David-Else]

@the-mikedavis It is done! I made your suggested changes, and re-read the entire thing and made a few more corrections/changes. If you and @archseer are happy with them we are ready to merge :) Please could you squash it down to get rid of all the unwanted commit titles, Rewrite and refactor all documentation should be a good title.

I have left all the restructuring work to another pull request as we discussed.

[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?

[cd-a]

Agree, this is great work. Thank you!