Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve front page and initial onboarding documentation #51

Open
username223 opened this issue Jan 1, 2021 · 0 comments
Open

Improve front page and initial onboarding documentation #51

username223 opened this issue Jan 1, 2021 · 0 comments

Comments

@username223
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant