search

zmkfirmware / zmk

ZMK Firmware Repository
https://zmk.dev/
MIT License
2.71k stars 2.76k forks source link

Better Documentation around configs #2534

Open SamBobBarnes opened 1 week ago

SamBobBarnes commented 1 week ago

I ran into an issue recently that could have been mitigated with some teaks to the documentation. Specifically, https://zmk.dev/docs/config. It would have helped a ton to have an example file structure for a minimal config. I was tripped up because I didnt understand that the my-keyboard.conf file needed to belong in the config folder rather than the shield/my-keyboard folder.

caksoylar commented 1 week ago

Where did you initially come across adding that file? I am asking because although we have it documented in a few places, it is still a frequent footgun for users.

For reference, the config page mentions:

Shared config files (excluding any _left or _right suffix) are not currently supported in shield folders.

New shield docs have this note (if you select the split tab):

The shared configuration in my_keyboard.conf is only applied when you are building with a zmk-config folder and it is present at config/my_keyboard.conf.

I'd say that maybe moving that remark next to "Configuration elements affect both halves" would be better.

It would have helped a ton to have an example file structure for a minimal config.

This is a good idea, I can see that helping in https://zmk.dev/docs/development/hardware-integration/new-shield#new-shield-directory.

For the Configuration Overview page, maybe adding tabs for non-split/split (and/or ZMK/config/module) would make it clearer in which cases it applies to.