Offer overview of all keymaps in the readme.

[htgoebel]

Please rename the keymaps (directories) to some scheme.Currently esp. the ergodox keymaps are quite a mess and spotting those to be a good base for someone's own mapping is hard. Example: coderkun_neo2 (at the far to), german... (in the middle), software_neo2 (near the end).

This may be acceptable right now, but will become a real mess if (hopefully) even more keymaps are contributed.

I suggest renaming these to some schema like country-variant-author. So the ones above german-neos-coderkun, and german-neo2-software.

IMO it does not matter that much whether the first part is the language or the country, but it should be consistent. (When looking at /usr/share/X11/xkb/symbols/gb I come to the conclusion that it might actually be better to use the country, not the language.)

[jackhumbert]

I'm a fan of this! _[ISO 3166-1 alpha-2 code]-[layout variant]-[layout name/author]_ eg us-qwerty-jackhumbert sounds like it would cover all the bases. If a keymap supports more than one layout, maybe something like us-all-jackhumbert would be appropriate (even if it doesn't actually support all of them).

Underscores (_) would probably be more appropriate here, since that's what a decent part of the firmware already uses, but I actually like dashes (-) a bit more - are there any reasons to go one way or the other in general?

Edit: I think multi will work better instead of all, eg us-multi-jackhumbert.

[htgoebel]

Fine :-) Re. dashes vs. underscore: I personally like dashes more, too, but I'd not care that much. The important part is using the schema.

[ezuk]

I like this quite a lot. I do want to be the devil's advocate here however, and raise a few questions.

1. Often, what makes a keymap unique or interesting is not the layout or the country used. Zweilander or whatever, or the Ordinary keymap is a great example. So sure, it's a US QWERTY layout. And that sounds really boring, and would do the opposite from what we're trying to do here -- by hiding it under a mundane name, we would be making it less easy to find rather than more. So how do you capture what's unique in a layout? By just having an arbitrary name, this at least gives the creator a shot.
2. Personal expression. These layouts are contributed by users out of their own volition. They work very hard to create them. We don't give them anything in return. Being able to creatively label your own work is an important element of personal expression, not being made to feel like you're put into some box and you have to do this, but you are doing something a little crazy and creative, giving away your work for free.
3. Our massive collection of existing keymaps: Who is going to go over them and rename them? And who is going to ensure this doesn't upset any of the people who've worked so hard to create them? There are some exceptional gems there and we need to be respectful of the creators.

[jackhumbert]

I think keeping the third element the layout name, and totally customisable is key - that satisfies 1 and 2, and 3 could be accomplished by prefixing most of the current names with our best guesses. Some like "german" or "colemak" would need to be customised a little bit (perhaps to the author's name), but it looks like a lot of them can just be modified to fit a schema.

Do you think a keymaps/readme would be necessary, where people could read about all of the keymaps in little snippets? I know we already have readmes in each of the keymap folders, but it might be nice to see all of them together with short, one-line descriptions, and let the keymaps//readme explain things in detail.

[ezuk]

I've been thinking about a keymaps/readme.md for a while now. Yes, I think that's a very good idea. Again, the challenge here is with going over all of the existing ones and writing concise descriptions for them. A fairly massive task. @eltang to the rescue? Wanna help with some docs, Eric? :)

[eltang]

@ezuk Thanks, I'll see if I have time (I've been a little busy lately). I actually do have some unfinished changes to the main docs sitting in a branch, though.

[ezuk]

I guess where I land on this is that the general idea is nice, but the implementation effort, especially for the EZ, is not trivial. If someone wants to rise to the challenge and (1) make a nice index and (2) rename the keymaps sensibly per this format, I'm all for it :)

[jackhumbert]

I'm playing around with this a bit here, but I'm not sure how useful it is for the Planck ones - I might make it optional for mine, and let those that do prefix a _ to pull it to the top, eg _us_multi_jackhumbert or jackhumbert.

[ezuk]

I quite like that voluntary approach with the little underscore as a bonus :)

[algernon]

Having tweaked my layout (ergodox_ez/algernon) heavily, I'm not sure how it would fit any of the proposed naming schemes. While the version currently in the repo is almost stock Dvorak, it has a number of keys in different positions already, and the next update will push it even further from Dvorak. Not to mention that the layout is for dual language use: English and Hungarian (one could argue that English is the primary language, but some of the changes I'm playing with are driven by Hungarian). So _us_multi_algernon comes closest, but... that's not any more useful than the current name.

When I was browsing the keymaps (I went through each and every keymap in the firmware, regardless of keyboard), the single thing I missed most is a way to search them for keywords, or tags. If one would be able to say: give me a list of all dvorak-related keymaps, that'd be great. Same for keymaps that use the leader key, or one-shot layers/modifiers, and so on. I can do most of this with some clever git grep, but that's not friendly.

A separate thing, a website or service or whatnot, where people could tag the keymaps, and search based on those tags, would be much more useful than trying to shoehorn the basic properties into a short-ish name. For example, Ordinary, or my own layout are likely not interesting because the basic layout, but other choices made, that have little to do with how the alphas are laid out.

Perhaps the Wiki could be used for this purpose?

[ezuk]

I like the tagging approach much better than I like the directory naming. We're currently working on Fusion (the graphical configurator that goes along with QMK) and that's a feature I hope to create there.

[algernon]

Regardless of the tagging, an overview of each layout in the keyboard/<board>/readme.md file would also be helpful. It'd be easier to find the keymaps one's most interested in. (I revisit the keymaps from time to time to see if there's anything interesting I can borrow, but I rarely remember which ones I found useful in the past - an overview would help remember)

[skullydazed]

Do we still need this issue open, or has it been supplanted by #753 and other newer efforts?

[htgoebel]

Since this ticket is about a readme, I'd consider this done.