Kakoune has generally good documentation, and pretty much everything you need to know to use Kakoune interactively and write scripts is in there somewhere, but sometimes it can be hard to find the thing you want to know, or even to discover that it exists in the first place. For example, the
commands page documents most commands, except for things like
map, which have their own pages, except for
eval which share a page. None of those pages actually talk about how command arguments work, though - that’s
command-parsing mentions expansions, but doesn’t go into detail since the
expansions page is all about them, although it mentions parsing in return.
Just today somebody made a PR adding a bunch of details to the
expansions page, and when I pointed out that it duplicated some of the information in the
command-parsing page, they said:
I didn’t realize the
command-parsingpage contained that (I don’t think I’ve ever actually read it to be honest). The information [in this PR] is what I though was missing from
expansions(and ended up learning from looking at the source code).
It seems to me that Kakoune’s documentation has grown organically, with things being added and amended over time as Kakoune has added and changed features, but without much attention to the larger structure.
- does anybody else agree that it can be difficult to find things in Kakoune’s documentation?
- would anybody else like to see the documentation reorganised?
- is anybody willing to contribute financially to reorganising the documentation?
If nobody has a problem with the state of Kakoune’s documentation, then fair enough. On the other hand, if there’s consensus that Somebody Should Do Something, I’ll start thinking about what a reorganisation might look like, when I can find the time. After all, I’ve already contributed to Kakoune’s documentation, and I’ve written long-form documentation before. If people are willing to contribute financially, I’m willing to make the time.