Changes to Documentation

[jackhumbert]

Collaborators, please edit this list.

• [x] How to fork QMK and make PRs through Github
• [x] Better introduction, with audience consideration
• [x] Add existing pages from the wiki to docs.qmk.fm (for example Eclipse setup and Unit Testing)
• [x] Delete obsolete documents from the docs folder
• [x] Document all special QMK keycodes
• [x] Document all config options
• [ ] How to use a Teensy 3.2+
• [x] Updated FAQ
• [x] Fix terminology (for example "active layer" vs "valid layer")
• [x] Add a glossary defining all key terms
• [x] Describe how to setup Visual Studio Code
• [x] Style guide for keyboards/keymaps

[ezuk]

IMHO "how to fork qmk and make PRs through Github" might fall a little outside of what we'd like to address. I think knowing how to use github is a valid prerequisite for contributing to an open-source project? Just my two cents.

[ezuk]

Also, added an item for making a glossary. We can break that out into its own issue if you'd like.

[fredizzimo]

Regarding Git guides.

IMO, this project is a bit different than most other open source projects. In order to use a normal project it's enough to just clone or download the zip of the project and build it, and you are done. In our case you need to modify the source code by adding your own keymap, unless you are happy with one of the existing ones.

I would also like people that create their keymaps to version them, rather than just having some local changes on their local harddrive. In this case you already need to fork QMK, and things start to get quite complex having to work with two remotes.

Furthermore, we want to encourage the people that make those keymaps to share them by sending pull requests. And since we can't expect them to be as experienced as someone that has the skill of changing a normal open source project, I think a guide is perfectly in order. In fact I people some people that make new keymaps are not programmers at all, they might need custom layouts for other things.

I have also seen people doing pull requests by using the Github interface directly, uploading files there, which is not something that I would ever recommend, since it's not at all sure that the pull request really represent the same version as the user tested locally.

The guide should not be a complete guide to git, but something very simple that anyone can follow. If we can find some nice beginners guide we could also alternatively link that. However most Git documentation that I see is quite complex.

[ezuk]

Cool @fredizzimo -- I see what you're saying :)

[skullydazed]

I did some work on this today. I removed a bunch of duplicate, out of date, or otherwise seemingly unnecessary files:

    deleted:    build_guide.md
    deleted:    build_old.md
    deleted:    cygwin_guide.md
    deleted:    embedding.md
    deleted:    git_subtree.md
    deleted:    hhkb_alt_controller.md
    deleted:    keymap_config_h_example.h
    deleted:    keymap_examples.md
    deleted:    keymap_makefile_example.mk
    deleted:    keymap_old.md
    deleted:    kiibohd.asciidoc
    deleted:    license_clarification.md
    deleted:    license_clarification_details.md
    deleted:    mbed_cortex_porting.md
    deleted:    memory_write_error,_use_debug_for_more_info.md
    deleted:    other_projects.md
    deleted:    pcb_guide.md
    deleted:    previously_asked_questions.asciidoc
    deleted:    report_descriptor.md
    deleted:    test_for_asciidoc.asciidoc
    deleted:    tmk_based_projects.md
    deleted:    tmk_own_projects.md
    deleted:    tmk_readme.md
    deleted:    usb_hid.md

I also spent some time updating some other things. These are the only files that I haven't either removed or added to _summary:

$ for i in *; do grep -q $i _summary.md || echo $i; done
_summary.md
becoming_a_qmk_collaborator.md
compatible_microcontrollers.md
fuse.txt
gitbook
hand_wire.md
keycode.txt
porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md
power.txt
usb_nkro.txt

I also updated the FAQ a bit but I haven't checked that off because there's more that can be done there. I have no plans for that one so if someone wants to work on that before I get to it more power to you. :)

[skullydazed]

I went through all the docs and fleshed out the glossary pretty well: https://github.com/qmk/qmk_firmware/blob/docs/docs/glossary.md

If I've missed anything please feel free to add it, but otherwise I think this is complete enough to check off the todo item.

[Wraul]

Not sure it this is the right place, but I believe it relates to the documentation.

When I worked on some contributions a while ago I felt that the contribution guidelines lacked code style guidelines. For example, should I use tabs or spaces, are there any constructs that should be avoided and so on.

[ezuk]

@skullydazed awesome glossary! I've just added a small note at the bottom inviting further contributions.

[drashna]

Only thing left is the Teensy 3.2?

[skullydazed]

With some other things in the works I think we can strike the teensy 3.2 from the list now.