Skip to content

Season of Docs 2019

Jump to bottom Edit New page
Gergely Nagy edited this page Apr 23, 2019 · 17 revisions

Kaleidoscope is applying to participate in Google's Season of Docs in 2019, this is the landing page for that. This page is a collection of information regarding the Season, including a link to ideas and any other useful information.

Kaleidoscope is a plugin- and Arduino-based firmware for computer input devices. The firmware tries to follow the Arduino tradition of making common tasks easy for the novice user. One of our goals is to allow one to get started fast, without little prior knowledge. Documentation is a key part of that.

Ideas listed below also have their corresponding issue on the main Kaleidoscope repository, all labeled with Season of Docs. Not all of them are listed here as projects, feel free to add missing ones. If you have a new idea, please open an issue, and copy & fill out the template at the end of this page too.

Table of Contents

Organization information

Ideas

Document the hardware plugins

  • Project name: Document the hardware plugins
  • Description: Our hardware plugins lack documentation. At the minimum, they should contain a brief description of the hardware, links to the device's homepage, vendor or any relevant page. We should also document the limitations of each plugin (eg, the EZ-ErgoDox plugin doesn't support LEDs yet, neither the EZ Shine, nor the EZ Glow; Planck only supports AVR variants and no sound, etc).
  • Difficulty: Very easy
  • Issue: #628
  • Related material:

Document driver::mcu

  • Project name: Document driver::mcu
  • Description: We recently introduced a driver::mcu namespace, the goal would be to take the in-code docs and algernon's blog post (see related material below), and write documentation for the namespace (including rationale) and the helper class in it.
  • Difficulty: Easy.
  • Issue: #627
  • Related material:

How to add a modifier to a key on the keymap

  • Project name: HOWTO: Add a modifier to a key on the keymap
  • Description: If there's one thing people often do with open-source firmware, making keys emit a key combo (a chord) is as close to one's "Hello World" as it can be. The goal of this project is to have a short, step-by-step howto that explains how to do this, and what limitations there are. The HOWTO should assume that the reader can already compile the unmodified factory firmware.
  • Difficulty: Easy.
  • Issue: #214

How to write macros?

  • Project name: HOWTO write macros?
  • Description: Writing macros is another one of those things many of our users want to do, and where our existing documentation is more suited for the slightly more experienced reader. We'd like to have a step-by-step howto, which might not explain everything, but lets someone new to Arduino and programming in general, get started.
  • Difficulty: Medium
  • Issue: #630
  • Related material:

How to install third-party plugins?

  • Project name: HOWTO install third-party plugins?
  • Description: While Kaleidoscope ships with a large number of plugins built-in, there are some that aren't part of the bundle. We'd need a step-by-step howto that explains how to install and use third-party plugins.
  • Difficulty: Medium
  • Issue: #235
  • Related material:

How to work with the Focus protocol?

  • Project name: HOWTO work with the Focus protocol?
  • Description: Focus is the protocol we developed to allow the host and the keyboard to talk. It's a bi-directional communication protocol, upon which Chrysalis is built. While there is some documentation about the protocol, there is no guide to teach one how to work with it. The goal here is to have a guide that shows that, preferably with code examples in a popular language. Optionally, the documentation should have a list of Focus commands supported by the core firmware and plugins bundled with it, to make it easier to figure out what can be readily done with it.
  • Difficulty: Medium
  • Issue: #412
  • Related material

How to use Chrysalis?

  • Project name: How to use Chrysalis?
  • Description: We should have documentation about how to use Chrysalis, how to reassign keys, use the colormap, and so on. This documentation should also include a troubleshooting chapter for common issues (permission issues, ModemManager, etc).
  • Difficulty: Medium
  • Issue: Chrysalis#375
  • Related material:

An overview of the available Kaleidoscope plugins

  • Project name: An overview of the available Kaleidoscope plugins
  • Description: A high-level overview of the existing Kaleidoscope plugins (those bundled with the firmware only, not including third-party ones - though having those included would be a big bonus too). The overview would be just that, a brief description for each plugin, perhaps with a short use-case to demonstrate how it can be useful. Doesn't need to include code samples, a use-case description is enough.
  • Difficulty: Medium
  • Issue: #165
  • Related material

Architecture documentation

  • Project name: Architecture documentation
  • Description: We have a fair amount of in-code documentation, lots of examples, but no high-level overview of the Kaleidoscope architecture. We have helper classes, drivers, subsystems (think EEPROM-Settings or LEDControl), but no documentation of how the pieces of the puzzle fit together. the goal of this project is to create an overview that does just that.
  • Difficulty: Difficult
  • Issue: #163

Document how USB HID works

  • Project name: Document how USB HID works
  • Description: To have a deeper understanding of Kaleidoscope, how and why it does things, it's essential to understand how USB HID works. We should have a document that describes this, in relation to Kaleidoscope.
  • Difficulty: Difficult
  • Issue: #631
  • Related material:

Coding style guidelines

  • Project name: Coding style guidelines
  • Description: We started to develop our coding style guidelines, but to this day, the document has not been finished yet. The goal of this project would be to go over the existing documentation, remove parts which aren't applicable, update parts which we do differently, and add guidelines we use, which aren't part of the guide yet.
  • Difficulty: Challenging. There's a lot of information to process, both because the coding style we based ours on is long, and because one needs to be aware of the intricacies of embedded development.
  • Issue: #134
  • Related material:

Idea Template

NOTE: Do not edit this template directly, copy it and fill that out instead, and add an entry to the Table of Contents at the top of the page!

  • Project name: Choose a concise but descriptive title.
  • Description: A longer description of the documentation work required. Describe your initial idea in detail. Offer opportunities for any interested technical writers to expand or refine the idea.
  • Related material:
    • Link to the open source project that needs documentation. This should be a link to the matching issue on the Kaleidoscope repository.
    • If you're proposing a technical writing project that involves updates to an existing documentation set, link to that documentation set.
    • If you're proposing a tutorial or a set of how-to guides, describe the features or use cases that need documenting.
    • If you're proposing a contributor's guide, link to any existing README file or other relevant material if present. If there's nothing available yet, it's fine to say that.
    • Include links to similar documentation in other projects, if relevant.
Add a custom footer

Troubleshooting

Advanced Topics

Development and customization

Keyboardio Model 01 docs

Community

Clone this wiki locally