bl602-docs
bl602-docs copied to clipboard
Improve front page and initial onboarding documentation
The current Home page (index.rst
source, index.html
compiled) does not contain any information except for the same listing shown in the sidebar.
The Starter Guides do not mention that UART is used and that UART does not allow for debugging while JTAG does.
The Developer Environment docs do not mention how to connect the JTAG necessary for debugging.
IMO the questions that should be answered by the intro page are:
- What is the BL602?
A general short overview of who is making it, what its intended use is and the most important specs. Information from the wiki can be used here, but less specific.
- How does the user set up an environment for developing for the BL602?
Partially answered by the Quick Start guides. Improvements could be made such as moving the "Connecting to Hardware" portions out of the platform specific documents and better explaining setting up a developer environment and JTAG.
I propose the following structure for the initial onboarding documentation:
Home Page
Short description of BL602 as mentioned above.
Quick Start Guide
Same as the current header.
Preparing and connecting the hardware
Move the current "Connecting the Hardware" sections from Linux and Windows sections out here.
Mention differences in connecting with UART and JTAG.
Setting up a developer environment
Explain Eclipse/Freedom Studio/vscode
.
The docs for Eclipse/Freedom Studio are currently very sparse.
vscode
is described here.
Compiling
Describe Windows/Linux in separate articles.
Flashing
Again, articles for Windows and Linux.
Debugging
Describe using gdb
and vscode
as described here and here.
Examples
Gradual introduction and documentation to the different examples.