search

pine64 / bl602-docs

Documentation of the BL602 IC
https://pine64.github.io/bl602-docs/
65 stars 41 forks source link

Improve front page and initial onboarding documentation #51

Open username223 opened 3 years ago

username223 commented 3 years ago

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:

  1. 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.

  1. 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.