Documentation almost entirely absent

[gedankenexperimenter]

The code is almost entirely devoid of comments that would help would-be contributors, and what little there is assumes a lot of knowledge of the existing code. Likewise, there is almost no useful documentation for users who want to make even small changes to their own keyboards (even something as small as assigning keys in the keymap.

You guys have been doing a great job making Kaleidoscope work, but it is currently very difficult for others to contribute because of the lack of documentation and descriptive comments in the code.

[obra]

You're right that we're short on documentation. That's on me. It's something we're working to improve. It's relatively early in the life of the project and until relatively recently, large subsystems have had a fairly high churn rate.

In general, I favor easy-to-read self-documenting code over extensive inline comments. That is is, of course, no substitute for architectural documentation and inline comments explaining developer intent or tricky, non-obvious codepaths.

The goal for Keyboardio customers is that we'll have a GUI for doing remapping. That's something that @algernon and @TheBaronHimself have been working on as part of https://github.com/algernon/Chrysalis.

User-facing documentation for 'regular' sorts of configuration is something we're trying to have ready for when mass produced Keyboardio Model 01 keyboards starts getting into customer hands next month. At this point, we're very much still under water and working to resolve release-critical bugs for what will be the shipping firmware.

The commitment I've made personally to the folks we shipped test units to is that if they're not able to remap keys on their own, I'll build them a custom firmware build. Up to now, the issues customers have had are almost all installation and tooling issues. As far as I know, nobody who's tried to remap their layout has failed. But the process has unearthed a number of issues we're working to fix. And the problems people have had mostly don't match the documentation I would have written last month. So, that's useful.

All that being said, I'm going to close this GitHub issue and replace it with a few new issues for a couple of reasons.

First up, and most serious: while I'm sure it wasn't what you intended, it reads like a complaint. "almost entirely devoid of comments" and "no useful documentation" feel hostile and somewhat pejorative. Other than me, just about everyone contributing to Kaleidoscope is a volunteer. Most plugins include example usages, as well as README.md files describing their intended behavior and use.

Second, and partially on me for not documenting it: Issues should have some sort of concrete resolution possible. I agree 100% that we have serious gaps in the documentation, but right now, there isn't really any way to look at the codebase and this issue and say "yup. That's resolved." As part of resolving that, I'm going to split out specific, concrete documentation tasks that need to be addressed. Some of those are user-facing docs and some are developer-facing docs.

[obra]

I've opened issues #163, #164, #165, #166, #167, #168, #169, and #170 to reference a variety of specific doc tasks related to this issue. If there are other doc tasks, I've missed, folks should feel free to open more issues or drop me a note.