Documentation: provide an entry point

[josuah]

Note: this issue is on the public repo

Interpretation of Venkat point

As I understand what Venkat mentioned during the review, is that the current documentation enumerates the hardware, RTL and firmware features, and sometimes provide API usage, but does not explain where to start.

The goal would be that someone who did not know about our project at all can learn himself how to do everything they need without the need to constantly ask us, which slows down development.

Personal point of view

Better modify the current content rather than add a new documentation on top, to avoid a "doc (new copy 2)" impression.

Better link to an external page, eventually with a summary, rather than copy-paste the content and never update it.

The most people involved, the easiest it will be to use the doc, as it permits to make sure the doc is understandable for somebody else.

Not everybody understands every corner of the tinyCLUNX33 (or Zephyr, Radiant, CrossLinkU-NX-33, or SpinalHDL, or LiteX...). Writing a documentation for teamwork might boil down to ask every team to summarize their involvement and integrate it.

Understanding of the whole system is often required to document the part, so discussions about how the whole system work are essential, otherwise it is not possible to explain it.

Hints for writing more documentation for the tinyCLUXN33 project

A good starting point is a short introduction document that presents the project, its features

1. Identify scenarios of users: what would be their background (i.e. firmware engineers who never did Zephyr, RTL developer who needs to customize a Zephyr build, firmware developer who wants to debug an RTL bug...). Discussions with clients are good starting points to get ideas.

2. Define an entry point that is given to everyone. Likely start from https://tinyvision.ai/.

3. Try to follow the path that each of these category of users would follow, and take note of each of the missing information they would need in order to jump to the next step.

4. For every step explained, include a way to verify that this worked, and instructions for debugging it if not.

5. For a lot of explanations, there will be instructions that are in common. Group them in dedicated page when relevant and link them from every page that needs them, i.e. "first complete this, then follow with these steps".

6. This would eventually end-up being a lot of chapters/pages/section. Try to group them in categories so that the content is where users expect them.

The current documentation only covered the hardware, and only a few steps of the firmware and RTL: it is not a complete example of what should be done, but the starting point.

Source of inspiration for the general style:

• (venkat) Infineon/Cypress app notes, such as https://usermanual.wiki/Document/FX3PROGRAMMERSMANUAL.1761659799.pdf
• (josuah) Zephyr doc, as there will be come-and-go by firmware developers between our doc and "upstream" doc.
• (josuah) Lattice doc, as we can expect RTL developers would be used to this documentation format.
• (josuah) The USB 2.0 standard, which are one of the few giving a complete introduction of what the whole idea is and follows onto the detail, and finishes by an enumeration of each particular feature.

[josuah]

I propose to add one message here for every error we encounter, along with their cause, so that we can later add them to the documentation in batch.

[josuah]

E: Failed to assign endpoint addresses

E: Failed to assign endpoint addresses
E: Failed to init SS configuration 1
E: failed to initialize USB

=> missing ep@... declarations in app.overlay: there should be enough endpoints declared for the particular USB protocol in use.
Refer to the existing examples for possible combinations.

[josuah]

@alanridel if you have something ready, let me know so that I can start working on documentation too. Thanks!