While @jesse is busy in China, I offered my help in getting as much of the plugins in an “1.0.0” state as possible. This means that they should be reasonably stable, and documented too. I’m starting with the plugins used by the factory firmware, and most of them have some documentation by now. However, I have a little problem: I’m not good at writing useful documentation, or even good documentation. Thus, I’m asking those of you, who feel up to the task, to review the documentation available.
I know it is a hard task, when you can’t easily try things, so what I’m most interested in, is suggestions about style and structure. (And pull requests on GitHub are more than welcome!)
There are other plugins used by the factory firmware, but they are lacking documentation as of this writing. Once I’ve added some, I will update this post with their links too.
There are many other plugins which will need similar treatment, but are less important, as they are not part of the factory firmware. If any of you is feeling generous, there is a list here. Click any of the Kaleidoscope-something links, and you’ll end up at the plugin’s repository, with the README.md file displayed below the file list.
How about some documentation for people who haven’t used Arduino before, but want to make their own keyboard configuration using Kaleidoscope and its plugins? I get as far as “To use the plugin, simply include the header in your Sketch…” and you’ve lost me. This might as well be “Simply jargon jargon jargon…” for anyone who’s not familiar with Arduino, and not everyone who wants to customize their keyboard is interested in – or has the time to devote to – learning how to program a general-purpose Arduino device. You’ve left out steps 1, 2, 3, and 4, and they’re nowhere to be found in the documentation for Kaleidoscope or any of the plugins.
I’m an experienced software engineer. If I spend a whole bunch of time researching Arduino and experimenting, I can certainly figure out how to make my own “Sketch” (whatever that is), and make it work, but I’d really rather not spend all that time, when there are people who already know who could probably write step-by-step instructions in half the time it would take me to figure it out. And presumably, we want this to be accessible even to people who aren’t programmers, too.
Working on it! There will be a set of guides that introduce the reader to every concept (not in detail, just enough to get their feet wet), and a bunch of “How do I…?” - style guides. It’s nowhere near complete, but I hope to spend some time on it this week.
I had looked there, and assumed it was for some other purpose. =)
I’d like to recommend starting with step-by-step instructions for someone who wants to simply re-assign the keys on their keymap, starting with downloading Arduino & Kaleidoscope, then building their own sketch (starting from the Model01-Firmware sketch, I suppose).
Then build on that by adding one plugin (I’d recommend starting with OneShot, and show both how to do it globally and how to do it for individual modifiers).
The most important thing is to not skip any steps. I’ll be happy to make sure any missing steps get filled in, though I can’t yet verify that any of it works, since I have no hardware.
Yep, that’s the next story to come. Well, almost. It will mostly be about Kaleidoscope, as a kind of not-too-technical intro into the core concepts. Then they’ll get down to business and install Arduino, and poke at the firmware.
I’ll be very, very interested in such feedback! The goal afterall is to have a funny little guide that people can use to get started with. I’d rather write more stories than skip steps. It is easier to skip through parts one’s not interested in, than it is to figure out the bits that aren’t documented.
I’m also willing to review documentation, but I don’t know anything about Arduino, so would need it to be step-by-step, starting from the very beginning.
I’d much rather have straightforward step-by-step instructions, and skip the stories, myself. For example:
Type the following command to install Arduino: …
Type the following commands to clone/create the necessary git repositories: …
Edit file X to remap some keys as follows: …
Flash the firmware with this command: …
How long would it take to write that up (but with actual details) so that someone with a Model 01 could get started gradually building up their own configuration? It ought to make debugging issues people report simpler, too, if they’re not just left to their own devices in figuring out how to make a sketch, but have a recommended pattern to follow.
I think it would be nice if both existed, they serve different audiences.
If I wrote it, and had to skip the stories, It would take ~forever. I’m not good at writing things I wouldn’t read myself. But! The good news is, that the steps will be easy to extract from the stories, so after a story is written, I can lift the steps out, and turn it into a step-by-step, story-less guide.
So the two can be done in parallel: I first write the story, because I find that much more fun (and if something is fun, I do it considerably faster), and then either me, or someone else can lift out the steps to another, more to-the-point kind of guide.
So, yep, fully agreed, having a step-by-step guide would be awesome too, and having written this response made me realize I can do both at the same time.
In that case, would someone who already understands how to do it other than @algernon care to help out the people who don’t? Even without all the details, some instructions would be better than the nothing that we have right now.
If nobody has done it yet by the time I next have some free time for this (the last week of August, probably), I’ll make some guesses and write it up myself, then people who actually have hardware and genuine knowledge of how it works can make corrections.
That’s the kind of step-by-step guide I’m getting at, but it only gets the user as far as (re)flashing the keyboard with the default firmware. It doesn’t provide any guidance or even hints about how to make one’s own customized firmware.
Should one make a copy of Model01-Firmware? Make a new repository from scratch?
What files should be modified to make changes? And how?
The plugin docs (such as they are) refer to a thing called a “Sketch” – what is that?
These questions (and more) need to be answered clearly with step-by-step instructions, or many people are likely to just give up.
I don’t think anyone is disagreeing that we need such tutorial documentation. As I said earlier, I know the existing customization documentation is deficient. That’s why our promise to everyone who got a PVT keyboard is that I will personally do whatever layout customization they need if it’s not easy for them. I…very much do not want to have to make the same deal for the thousands of folks who have preordered keyboards.
Er, to clarify, I will make that same deal for the thousands of folks who have preordered keyboards, which means that the documentation and tooling has to get better.
