search

zmkfirmware / zmk

ZMK Firmware Repository
https://zmk.dev/
MIT License
2.77k stars 2.8k forks source link

docs: Expand the troubleshooting section to add FAQs for common issues #1234

Open caksoylar opened 2 years ago

caksoylar commented 2 years ago

There are a few common problems that folks run into and they usually get helped in the Discord, but I think they can be documented in the Troubleshooting page with steps to help debug and resolve them.

It would also be nice to pose them like FAQs, but we already have an FAQ page which doesn't deal with any troubleshooting questions. I currently have two such issues in mind with a sketch on what the recommendations can be:

  1. "My keyboard works over USB but not Bluetooth":
    • The current warning note about USB power can be moved under this section
    • We can recommend the usual steps for working with profiles (clear current profile or move to an unpaired profile, make sure this host is not paired on another one) and provide a pointer to BT docs
    • Can also mention that keyboard name might not be set properly if it is a custom board/shield
    • Point back to "connectivity issues" section for intermittent problems
  2. "My battery is running out too quickly":
    • Point out that smart LEDs still consuming power even if off and point to external power behaviors
    • Suggest looking at solder/flux bridges between MCU pins that might leak current
    • Can link to power profiler to figure out expected battery life
    • Note that Windows BT battery reporting is flawed

If anyone can think of other common issues that could be a good fit we can note them in this issue as well.

Edit: Updating with a few more suggestions from below.

  1. "My compiled firmware size seems too large / does not fit on my board"
    • Suggest running west build -t rom_report and ram_report to see at a breakdown of things
    • Tweak flash/ram partition sizes?
  2. "My key presses are doubled"
  3. "I built a split keyboard but the right half doesn't do anything"
    • Explain that the right hand firmware only communicates with the left side, so left side needs to be turned on and paired
    • If flashed left side firmware to test right side, need to go through settings-reset procedure before flashing right side firmware
dxmh commented 2 years ago

It would also be nice to pose them like FAQs, but we already have an FAQ page which doesn't deal with any troubleshooting questions.

I think that an FAQ-style troubleshooting page would be a helpful format. Perhaps if we restructure the Troubleshooting page as you propose, we could simply continue to refer the page as "Troubleshooting" in the sidebar – leaving FAQ as-is?

dxmh commented 2 years ago

If anyone can think of other common issues that could be a good fit we can note them in this issue as well.

A quick one from the top of my head that popped up yesterday, it's not super common, but we do see questions about firmware size from time to time and this tip seems to be rather unknown:

Examples where this has come up:

dxmh commented 2 years ago

If anyone can think of other common issues that could be a good fit we can note them in this issue as well.

We could also mention "double keypresses" and link to the Debouncing docs. This one also comes up now and again.

caksoylar commented 2 years ago

Thanks @dxmh!

I think that an FAQ-style troubleshooting page would be a helpful format. Perhaps if we restructure the Troubleshooting page as you propose, we could simply continue to refer the page as "Troubleshooting" in the sidebar – leaving FAQ as-is?

Yeah, I think this is a good idea. Some of the existing section headings would need to be renamed.

I added the two other issues you described to the main post. I also added a big one I had missed re: right half of split keyboards. It can refer to a page like proposed in #948 when it exists.

dxmh commented 2 years ago

Here’s a couple more FAQs:

caksoylar commented 2 years ago

Would it be worth having a separate keymap/behavior-specific FAQ section? That way we can have one focused on troubleshooting problems and another on common keymap use cases.

dxmh commented 2 years ago

That sounds good. Less of an FAQ and more like a "tips and tricks" section for using features and behaviors in creative ways. 🙂

dxmh commented 2 years ago

Another for the troubleshooting FAQ?

Q: My keyboard causes my computer to wake from sleep periodically.

A: There are reports of macOS being woken by the battery status notifications. One workaround is to enable deep sleep for your keyboard, which will prevent the broadcast of battery status notifications.

References:

Related issue: https://github.com/zmkfirmware/zmk/issues/1273