User Experience Study Recommendations

[MaureenHelm]

The following recommendations were made as a result of an Intel user experience study:

Documentation for early-phase developers:

• What is the development model for RTOS (differences from bare metal or standard OS application)?
  development)

• What is device tree and how to use it?

• How to integrate sensors, drivers, and set configurations

• Zephyr vs. Linux concepts (where the same, where different); leveraging Linux experience with Zephyr

• Porting to custom boards; step-by-step tutorial

• Memory management, preventing stack overflows, debugging tips

• Document how Bluetooth and TCP/IP stack calls in Zephyr are different than Linux or Windows

• Introduction to new tools like West. Be clear about optional versus required use

• More information about West and how it uses Kconfig, DTS, Cmake

• Create architecture diagrams to help with some of the topics above

• Update error messages to be very specific to the error experienced to enable root cause identification

• Adding tools to help with multi-thread application development and de-bug

• Comprehensive sample app and tutorial.

[mbolivar-nordic]

I'm revisiting these recommendations since I've had mixed results trying to fix some of these problems and I'm listed as a potential mentor on the GSOD project to work on them.

In my opinion, this one is "done":

• Porting to custom boards; step-by-step tutorial: The board porting guide has had step-by-step instructions for a while and we've seen good feedback in the wild

Here is a progress report on some others from my point of view:

• What is device tree and how to use it?:
  • "What is devicetree" is documented in the DT guide now (especially in Introduction to devicetree)
  • "how to use it" could use a lot of improvement. IMO:
    • Docs on writing device drivers using DT should be separate from from application development using DT. These end up being pretty orthogonal tasks but the docs for them are mixed together, and unfortunately are documented in a silo inside the DT guide, separate from the more easily discoverable driver model and application development pages. This evolved organically and deserves a redesign with better information architecture.
    • We also need more HOWTOs for common use cases. In my experience helping users, "how do I configure I2C, SPI, GPIO, and pinmux on my SoC?" are FAQs that deserve dedicated content, as do "how do I hang a sensor / flash chip / GPIO expander / etc. off of my SPI or I2C bus?". I suspect the DT HOWTOs page is not the right place for this because I subjectively "often" link users to it when they ask questions that are already answered there.
    • Better debugging advice related to accessing the DT from C is needed. DT errors can be scary, spanning dozens of lines of compiler diagnostics for a single typo in a C file. I've collected various debugging tricks that aren't documented and definitely should be.
• How to integrate sensors, drivers, and set configurations:
  • You can discover this from first principles starting from the DT guide and the Kconfig guide, then digging around in the Kconfig and driver source files throughout the workspace, but it's a steep learning curve.
  • I think the DT bindings index is a good start for using a particular binding, but there are still well known gaps from there to tying it together with Kconfig for a particular driver which I summarized here.
  • I prototyped a framework for closing these gaps here, but abandoned it as impractical and have not had time to revisit.
  • Generating hardware support info in board documentation from the BOARD.dts files, which IMO is the last step in fixing this, is also a longstanding TODO, of course.
• More information about West and how it uses Kconfig, DTS, Cmake:
  • The build overview has good info on how the pieces fit together (I didn't write this page)
  • It's a common misconception that west build is much more than a wrapper around the CMake build system described in the build overview. That's all it is, though. west build does have its own documentation which I hope is reasonably complete, but the misconception persists. IOW, the docs are there, but they must not be structured properly to make it easy for new users to understand.
• Create architecture diagrams to help with some of the topics above: I think there are actually a fair number of good ones at this point, but they're each in their own silos.
• Introduction to new tools like West. Be clear about optional versus required use:
  • I believe the west guide finally accomplished this in the docs for the west v0.9.x releases
  • No other "new tools" are explicitly listed, but IMO the twister docs might benefit from some more iterative improvements. I see questions from new contributors about how this all relates to CI, and how to reproduce CI issues locally, fairly often.
• What is the development model for RTOS (differences from bare metal or standard OS application)?
  development): Again, this exists, but maybe is not written down in one place. @carlescufi and I wrote an LWN article which may serve as the basis for a more digestible page in the docs for this.
• Zephyr vs. Linux concepts (where the same, where different); leveraging Linux experience with Zephyr: see previous bullet
• Comprehensive sample app and tutorial: in progress, see Preliminary example manifest+module example-application#1

I don't feel as qualified to comment on these since I haven't worked on docs for them directly, but perhaps @carlescufi or someone else will chime in:

• Memory management, preventing stack overflows, debugging tips
• Document how Bluetooth and TCP/IP stack calls in Zephyr are different than Linux or Windows
• Update error messages to be very specific to the error experienced to enable root cause identification
• Adding tools to help with multi-thread application development and de-bug