A List of Problems with Helix's Documentation and Proposals for Solutions

[David-Else]

UPDATE: See the PR that this discussion spawned: Rewrite and refactor all documentation #5534

A List of Problems with Helix's Documentation and Proposals for Solutions

1. Some sections of text are not clearly written and need to be revised, for example:

Helix's editing model is strongly inspired from Vim and Kakoune, and a notable difference from Vim (and the most striking similarity to Kakoune) is that Helix follows the selection → action model.

Could be expressed as:

Helix's editing model is inspired by Vim and Kakoune, but unlike Vim it follows the "selection → action" model, like Kakoune.

2. The documentation frequently switches between first, second, and third person, the 2nd person pronoun you should be used where possible

3. There is outdated and missing information in the documentation, such as:

Please note: there is no icon for Helix yet, so the system default will be used

There is no information on how to download Helix for RHEL 9, even though it is now supported in the COPR.

4. Table items sometimes end in ., sometimes not

5. There is inconsistency between triple tick code block, sometimes they have no language specifier, sometimes they end in bash. I think they should generally end in sh for terminal commands entered by the user, these languages are available in GitHub:

6. The documentation sometimes assumes that the heading is part of the next paragraph, for example:

[editor.statusline] Section

Allows configuring the statusline at the bottom of the editor.

should be:

[editor.statusline] Section

The `[editor.statusline]` section of the configuration allows configuring the
statusline at the bottom of the editor.

7. The actual Markdown text that the documentation is written in has random formatting, sometimes it is set to 80 chars, and sometimes there is no formatting. I suggest it is all formatted to 80 chars, this has no effect on the rendered document but is much tidier.

What are the maintainers opinions on this list, and is there anything not covered? These are all just general good technical writing practices. @the-mikedavis I would love to hear what you think.

[the-mikedavis]

These all look good to me:

1. 👍
2. 👍
3. Ah, this was covered somewhat in https://github.com/helix-editor/helix/pull/5370/files but it exists in the book too. That should be fixed along with anything else outdated and anything that was fixed in 22.12 could be backported to the current release docs
4. I don't have a preference either way but I agree it should be consistent
5. I like sh as a default instead of bash 👍
6. 👍
7. I would also like 80 chars where possible to make it easier to view/edit locally 👍

The docs are a little inconsistent style or content -wise in some areas I think because they are contributed in small chunks by many contributors. A large PR that passes over most of the docs and makes them more consistent would be great

[David-Else]

@the-mikedavis Thanks for the feedback, I will start work on it soon, not sure how long it will take as it is quite a big job.

• I assume I should work on the master branch https://github.com/helix-editor/helix/tree/master/book/src ? I don't know where the current 22.12 docs live or how publishing them works.
• Once it is done we could copy the entire updated docs back to the current docs but miss out anything extra that applies only to the master post 22.12? Or maybe we would wait until the next release before the updated docs were published?

[the-mikedavis]

For small fixes like the note about the icon, I can push the changes to the right spot on the gh-pages branch. For larger changes I don't think we need to backport, they can wait until the next release to become the stable docs (master docs are published to https://docs.helix-editor.com/master/)

[David-Else]

@the-mikedavis I think the following would be a big improvement in the documentation structure. It would help people find the subject they are looking for much quicker and bring consistency.

All the # h1 headings, and following subheadings, should follow a similar format as 5. Guides.

# Main subject

Introduction and overview of what is to follow in the rest of the section.

## Topic 1 of subject

## Topic 2 of subject

etc...

Following this logic I would have:

# Usage

## Registers (also covering special registers)

## Surround

## Syntax-tree-motions

## Text Objects (including Tree-sitter Textobject Based Navigation)

## Keymap

## Commands

## Language Support


# Configuration

## Configuring the Editor

## Themes

## Key Remapping

## Language

What do you think?

[David-Else]

I have now rewritten and refactored all the existing documentation, keeping the same structure, but adding subheadings where I felt they were necessary.

I believe the entire documentation requires reorganization, and I have created a draft layout as follows. @the-mikedavis @archseer What are your thoughts on this? @pascalkuthe What do you think about Advanced Features/Version Control Integration documentation? We need to mention the Git Gutters and the current limitations I think. 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. I think it should explain what Helix is, include the logo, and serve the a similar purpose as the README. The documents 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 they go somewhere else? Add to Advanced Features?

There are a couple of essential topics missing from the documentation, such as code formatting and search and replace, 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.

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
• Finding additional resources (e.g. online tutorials, user forums)

[archseer]

Could you open a PR with what you have? I think it'll be easier to collaborate on with PR reviews than discussion comments

[David-Else]

Pull Request is now open :) #5534