Keyboard Refresh Project Brainstorming

[skullydazed]

As QMK has grown and matured the need for keyboard specific README.md files that cover QMK basics such as how to setup the build environment has been reduced. Worse, many of these files have instructions that are out of date or incomplete, making it harder for newcomers to figure QMK out. In reviewing keyboards many of them also have no copyright headers, making ownership and licensing of their source files ambiguous.

We'd like to institute a keyboard cleanup project, where we bring all keyboards up to a baseline standard of documentation and organization. This issue was created to talk about and decide on what this project will cover.

Open Questions:

• What information should be in a keyboard's README.md?
• What information should be in a keymap's README.md?
• What do we do when ownership of a keyboard can't be determined?
• What else should we consider including in this project?

[jceaser]

1. what goes in keyboard':
   • maintainer
   • hardware supported
   • build instruction
2. what goes in keymap:
   • maintainer
   • difference from standard layout
   • ascii art layout of keys and layers
   • intended usage
   • build instructions
3. ownership?
   • state abandoned status, support if well documented. "you document, we support"
4. Future
   • roadmap of supported features
   • most asked for layouts which needs an implementer.

[skullydazed]

Building on what @jceaser wrote:

Keyboard Documentation Standards:

readme.md

The readme.md for a keyboard should have the following information, in order:

1. A short description (1 paragraph, no more than 4-5 lines) of the keyboard
2. A block including the following information:

• Maintainer
  • No maintainer? List as "community maintained"
• Hardware Supported
• Where to get said hardware
• A link to the standard QMK build instructions

3. Custom instructions for building this keyboard, if any. Keyboard maintainers are encouraged to fit in with the standard QMK build process.

layout.json

To help facilitate documentation and configurators we are asking keyboards to start including a layout.json file. This file describes the layout of your keyboard in keyboard-layout-editor.com raw data code. The first line should be a "decal" saying "Layer 0". All the key legends should be blank.

For keyboards which support multiple layout options you should find a way to represent those options in a unified layout. (FIXME: what do we do when they can't, or when it's cumbersome to do that?)

Example for keyboards/clueboard:

[{a:6,f:9,w:3,d:true},"Layer 0"],
[{a:7,f:3},"","","","","","","","","","","","","","","",{x:0.5},""],
[{w:1.5},"","","","","","","","","","","","","",{w:1.5},"",{x:0.5},""],
[{w:1.75},"","","","","","","","","","","","","",{w:1.25},""],
[{w:1.25},"","","","","","","","","","","",{x:-1},"","","",{w:1.25},"",""],
[{w:1.25},"","",{w:1.25},"",{w:1.25},"",{w:2},"",{w:2},"",{w:1.25},"",{w:1.25},"","",{w:1.25},"","","",""]

Keymap Documentation Standards

readme.md

The readme.md for a keymap should have the following information, in order:

1. A short description (1 line)
2. A block including the following information:

• Maintainer
  • No maintainer? List as "community maintained".
• Difference from standard layout
• Intended usage

3. Custom instructions for building this keymap, if any. Keymap maintainers are strongly encouraged to fit in with the standard build process for their keyboard.

layout.json

This file should be keyboard-layout-editor.com raw data. Each layer should be represented as a separate block within the layout.json file. Each block should start with a "Decal" saying "Layer ".

Example for keyboards/clueboard/keymaps/default:

[{a:6,f:9,w:3,d:true},"Layer Typing"],
[{a:4,f:3},"~\nEsc","!\n1","@\n2","#\n3","$\n4","%\n5","^\n6","&\n7","*\n8","(\n9",")\n0","_\n-","+\n=","~\n`","\nBS",{x:0.5},"\nPage Up"],
[{w:1.5},"\nTab","Q","W","E","R","T","Y","U","I","O","P","{\n[","}\n]",{w:1.5},"|\n\\",{x:0.5},"\nPage Down"],
[{w:1.75},"\nCaps Lock","A","S","D","F","G","H","J","K","L",":\n;","\"\n'","~\n#",{w:1.25},"\nEnter"],
[{w:1.25},"\nShift","|\n\\","Z","X","C","V","B","N","M","<\n,",">\n.",{x:-1},">\n.","?\n/","|\n\\",{w:1.25},"\nShift","\n↑"],
[{w:1.25},"\nCtrl","\nWin",{w:1.25},"\nAlt",{w:1.25},"\nMu henken",{w:2},"\nSpace",{w:2},"\nSpace",{w:1.25},"\nHenken",{w:1.25},"\nAlt","\nCtrl",{w:1.25},"\nFn","\n←","\n↓","\n→"],
[{a:6,f:9,w:3.5,d:true},"Layer Function"],
[{a:4,f:3},"~\n`","\nF1","\nF2","\nF3","\nF4","\nF5","\nF6","\nF7","\nF8","\nF9","\nF10","\nF11","\nF12",{a:7},"",{a:4},"\nDelete",{x:0.5},"LED\nToggle"],
[{a:7,w:1.5},"","","","",{f:2},"",{f:3},"","","",{a:4},"\nPrint Screen","\nScroll Lock","\nPause Break",{a:7},"","",{w:1.5},"",{x:0.5},""],
[{w:1.75},"","","","","","","","","","","","","",{w:1.25},""],
[{w:1.25},"","","","","","","","","","","",{x:-1},"","","",{w:1.25},"",{a:4},"\nPage Up"],
[{a:7,w:1.25},"",{f:4},"",{f:3,w:1.25},"",{w:1.25},"",{w:2},"",{w:2},"",{w:1.25},"",{w:1.25},"","",{a:4,w:1.25},"\nFn","\nHome","\nPage Down","\nEnd"]

[jackhumbert]

For the keyboard readmes, this is the format we can follow:

Planck
===

![Planck](http://i.imgur.com/q2M3uEU.jpg)

A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/)

Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)
Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0
Hardware Availability: [OLKB.com](https://olkb.com)

Make example for this keyboard (after setting up your build environment):

    make planck-rev4-default

See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.

[jackhumbert]

I think we've implemented these changes a couple different times, so I'm going to close this for now.