Hi, @Screwtapello! Great initiative!
As a new user of Kakoune (I started using it this year), perhaps I can share some of my experience trying to get through the docs while my memory is still more or less fresh.
I think that the main problem of Kakoune documentation is that it is organised by concepts, more or less in the lines of the concept map sketched here. And this is a problem because, when you first enter the Kakoune world, you are initially not that interested in all the concepts, but in making the editor adapts to your workflow.
For instance, in my personal experience, when I started using Kakoune, I think I was trying to find answers for the following questions (and in the following chronological order):
- where’s the configuration file?
- how can I customise its appearance? Including:
- changing the color scheme
- showing line numbers
- line wrapping
- hiding the Assistant (yeah, yeah, I hide it, even though it’s cute)
- making a tab displays as 4 spaces
- how can I edit this buffer the Kakoune way instead of just do basic operations?
- how am I supposed to make new selections? Isn’t there an equivalent of the
<c-n> key of vim-visual-multi? If I can’t easily make new selections, why would I switch to this editor?
- how can I install plugins?
- how can I exchange
<a-c>? By the way, why replicate such an arcane and counter-intuitive behaviour from the old ages of
- how can I make new mappings?
- specially, how can I make a mapping to call
: buffer and make me select a buffer fast using Kakoune’s built-in fuzzy finder?
- how can I make a file with a custom extension being recognised as a known file type?
- how can I set custom options based on the file type?
- how can I define a new command to automate this thing I do often?
- how can I script Kakoune?
Note that organising the docs by concept (like commands, expansions, execeval, faces…) don’t help to answer most of the questions above fast. It certainly didn’t help me.
I remember I almost gave up migrating to Kakoune just because I thought it didn’t have line wrapping. I couldn’t find it in the docs regardless of how much I tried. How could I know it was in the highlighters section?! I saw this name – highlighters – and thought it was related to creating custom color schemes. It wasn’t until I decided to search the issues in the Github repository to see if there was any demand to implement it that I saw it was already implemented. Then, it took me some more time of searching in the issues until I finally found how to do it.
Perhaps we could try to figure out a way to organise the docs by action (how can I do what I want to do?) instead of concepts (what’s the definition of expansions?). I don’t know how exactly it could look like, but it could have at least these topics:
- UI customisation with code snippets as examples;
- editing text the Kakoune way (with lots of useful examples);
- behaviour customization, like defining mappings and dealing with hooks (with many examples);
- scripting Kakoune (with tons of good code snippets as examples).
And, please!, let’s think about writing good examples in the docs. They help a lot!