Keyboard organisation and brief descriptions in readmes

[jackhumbert]

There's still quite a few keyboards that don't have anything about them in their readmes - we should try to include some of the following in each:

• General layout/description
• If this is still being sold/made
• Where to buy/get
• Brief material list if different from standard keyboards (BT addons, LEDs, etc)

I'm thinking custom builds should go in handwired from now on - we shouldn't have a bunch of one-of-a-kinds in keyboards. These could have some of the following info:

• A little description about the build/insight into the mindset behind it
• Where/how parts were made
• Link to part files (not hosted here - please create a separate repo)

[IBNobody]

A few thoughts.

• I have been lax in populating the .md files for my boards. I can correct that.
• Do PCBs have to exist and be order-able for them not to be one offs? I open-sourced Vision/Division, and made the PCBs available even though I am the only one who owns one at this time.
• I would recommend that we work on showcasing useful examples in the main readme. Take my Retro Refit board. It used the keymap macro to fix a horrible key matrix.
• We should look at expanding the templates to have more than 5 keys. When I first got my start in TMK, I did so by looking at the design for the LightPad because it was the only other keypad in the TMK repo.

[IBNobody]

Another thought... While it is good that Planck and Ergodox have caught on, their keymap folders are getting kinda beefy. Can we retire keymaps from them?

Meanwhile, the Atomic repo has lots of room... for only me. :P

[absenth]

As a very recent Ergodox user, I think it would help if the Ergodox folder were broken into major layout styles.

For example, if all the dvorak based keymaps were in a dvorak folder, and all the colemak based keymaps were under colemak, etc. It would make finding a keymap close to what you are looking for far easier for new users.

[IBNobody]

@absenth Would it be less daunting if there were two keymap folders, one with reference layouts and one with user layouts?

[absenth]

@IBNobody that's actually not a bad idea at all. While I was waiting for my keyboard, I actually tried to find something colemak, that was otherwise very similar to the default Ergodox-EZ config, didn't find it, and gave up.

Now that I mention it, I think I should contribute almost exactly that back to the community. 👍

[jackhumbert]

Do PCBs have to exist and be order-able for them not to be one offs? I open-sourced Vision/Division, and made the PCBs available even though I am the only one who owns one at this time

I think it would make sense for things like this to start in the handwired folder - they can always be moved out once a group buy is done/they get popular enough.

Yeah, the template could be a little more complicated, but it's just arranging the rows/columns - what particular benefit did you get from looking at the LightPad? If it's just the layout, maybe we could have a script that would generate that with kxy.

Re the keymaps - they need organising, but that's a whole other issue (I think it was started in another issue, but I can't find it right now), so let's move that discussion somewhere else.

[jceaser]

I've made an attempt to give an overview of all of them, is there a document someone has already started that i can merge my comments into?

[jackhumbert]

The keyboards/readme.md has a brief explanation of each.

[IBNobody]

@jackhumbert

Yeah, the template could be a little more complicated, but it's just arranging the rows/columns - what particular benefit did you get from looking at the LightPad? If it's just the layout, maybe we could have a script that would generate that with kxy.

Backlighting, and the fact that it was in the shape of a keypad. Back then, I didn't understand why we had KEYMAP macros.

[algernon]

Regarding keymap directory reorganization: this came up earlier too, in #362, it is worth reading, because valid points have been raised there pro and cons. My main issue is that for a number of layouts, the alpha layout is not the defining factor. Ordinary, or my own - putting them under qwerty or dvorak would be naive: that's not why they are interesting. There are other a number of keymaps that support multiple layouts. There are some that are based on one layout or the other, but aren't really the same (mine for example is mostly Dvorak, but only mostly). Trying to fit one label onto a keymap is not all that useful.

From a user point of view, a place where the various keymaps are tagged with any number of tags, and they can filter on these tags - THAT would be useful. Much more so than any directory structure one can come up with. Because then, the keymaps are not shoehorned into one tiny label. I could search for, say dvorak, steno, tap-dance, one-shot, and so on.

But if a split has to be made, then reference/user makes the most sense, imo. Mind you, that will complicate either the makefiles, or the instructions noticably.

(I have no opinion on keyboards themselves, though. But I know I loved that I can see all the keymaps for the EZ, when I was browsing for ideas, made navigation much easier. I already knew I'll make my own, so seeing everything in one place made idea-gathering easy.)

[fredizzimo]

Regarding the readme files, I totally agree.

Let's also not forget the list on the readme.md file(which Jack already mentioned) in the keyboards folder. For people that just reads the main documentation at qmk.fm, that's the only way to discover the keyboards. I updated the community list a few weeks ago, but it's probably already out of date, and it doesn't contain the keyboards in the handwired folder.

My personal opinion regarding moving almost all the community keyboards to the handwired folder is that we don't gain anything by doing so. For users it just means that now they have to look in two different places to find out what keyboards are supported.

Furthermore, with the current makefile structure it's not possible to support revisions of the keyboards in the handwired folder, as they are already subproject, and we don't support sub-sub projects.

I understand from a commercial point of view, it would make sense to make it clearer, what level of support the different keyboards have, and which of them have official support. But the problem is where to draw the line, if only the officially supported keyboards are included in the root folder, then the handwired folder would still be quite big.

If we include other "major" keyboards in the main folder, there's still no guarantee that they are well supported by the community, in fact many of the handwired ones would probably be more supported due to active community members.

PCB vs hardwired as a separation doesn't make much sense either, take for example the mostly hardwired Katy keyboard, it's more of a product than many of the keyboards with a PCB.

If the concern is how to find interesting keyboards, I think a totally different structure would make sense, for example this

• Large
• Full Size
• Tenkeyless
• 60%
• 40% and smaller
• Ergonomic
• Misc
• Other devices (for example usb-usb converter)

But then there's other types of categories, like Staggered vs. Ortholinear/Matrix Sculpted vs. non-sculpted

I don't think we need a special directory structure for this though. The keyboards folder's readme.md file could be extended with categories. It could maybe even have some type of comparison table, similar to what you can see on Wikipedia for comparing different types of software for example.

We could also probably have the same type of overview for the keymaps, on the keyboard specific readme. At least for the keyboards with many keymaps, like the Ergodox and Planck.

[jackhumbert]

Moving this discussion to #1362.