docs: new user flow on website

[Genteure]

IMHO the way the website is structured is confusing for new users. There's no clear path from the home page to working keyboard firmware.

Clicking "Getting Started" on the home page doesn't lead to a page with useful next step instructions. It would be better if there's a clear and obvious path to follow from the home page to having compiled binary on disk.

From the perspective of two types of users:

Keyboard Designers / DIYers

The first pieces of information I'm looking for as a keyboard designer would be 1. what controller/chip can ZMK run on, and 2. how to configure and compile ZMK for my custom keyboard.

The answer to the first question is somewhat buried in https://zmk.dev/docs/hardware with a not too easy to read format. Without any prior knowledge about ZMK and Zephyr in general and without reading some explanation first, it's really hard to decipher what's "board" or "shield" or even "board variant". While that info exists on the site it requires clicking away and reading through the page.

The answer to the second question is https://zmk.dev/docs/development/hardware-integration/new-shield, which is not linked from in an obvious place.

End Users

I'm not really sure about what I would be looking for as an end user.

From what I've seen, most vendors have some kind of getting started guide and some kind of template repository users can fork, so I'm guessing most people just need to look up keymap related stuff.

[nmunnich]

I think we could further separate end users:

• Users who just need some firmware to flash so that they can start using ZMK Studio
• Users who want to customise their keymap/configuration in such a way that they are unable to do with Studio (e.g. switching to the internal oscillator of the nrf52)

For the first group, it would be very convenient to be able to just give them some prebuilt firmware to flash. While I'm sure some vendors do this, for various reasons a user may not be able to easily obtain such files in a trustworthy manner.

The second group needs to obtain a zmk-config and would usually nowadays start by needing to add a module to their config to build from there. Hence we get all of the forks of random repositories which already have the module bits setup for them.

I think all types of users have a somewhat painful onboarding experience for different reasons, and we could do better for all of them.

[caksoylar]

Thanks for detailing this, I agree with the overall argument and most of the details. As to what to do about it:

I like the approach in #3363 (and agree with points raised in Nick's review). The other piece that is missing is, IMO, is a sort of flowchart (not literally) in the Getting Started page. This should target the audiences separately, and point to the right section of the docs. Off the top of my head, combining with Nick's comment:

1. Users looking to use ZMK Studio -> link to Studio page
2. Users looking to use ZMK setup script to edit keymap/conf -> link to user setup
   • maybe rename the page from "Installing ZMK" to something else?
   • whether keyboard is upstream or not, the page does mention "My keyboard isn't listed" for external modules, but this can be promoted further
3. Users looking to write a keyboard config (DIYers/keyboard designers) -> Hardware Integration page
   • this index page can be improved to reorder sections add such a flowchart too, for shield vs. board etc.