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

[caksoylar]

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"
   • See Debouncing docs to tweak debounce timeouts
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]

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]

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:

• "My compiled firmware size seems too large / does not fit on my board"
  • You can run west build -t rom_report and ram_report to see at a breakdown of things.

Examples where this has come up:

• https://discord.com/channels/719497620560543766/781271311455748136/962022783821422694
• https://discord.com/channels/719497620560543766/719909884769992755/886258000778637322
• https://discord.com/channels/719497620560543766/719909884769992755/819809034009182219

[dxmh]

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]

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]

Here’s a couple more FAQs:

• How can I switch between Windows and Mac layouts?
• Does ZMK support autoshift? (Example achieved via hold-tap)

[caksoylar]

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]

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

[dxmh]

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:

• https://discord.com/channels/719497620560543766/719909884769992755/811654995761692703
• https://discord.com/channels/719497620560543766/784523018050469939/946242770241220678
• https://discord.com/channels/719497620560543766/719909884769992755/968492217649991761

Related issue: #1273