Make the readme easy to follow #1295
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Download the artifacts for this pull request: |
|
|
||
| [](./docs/tutorial/toc.md) | ||
| [](./docs/ONBOARDING.md) | ||
| [](./docs/ONBOARDING.md) | ||
| [](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/) |
There was a problem hiding this comment.
The page is being rendered with 2 "documentation" buttons, would it be too confusing? Do we want to keep both documentations files (Espressif Server + Github)?
| - Requirements for [MacOS](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/macos-setup.html#install-prerequisites) | ||
| - Requirements for [Linux](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-setup.html#install-prerequisites) | ||
| - For Windows there is no additional prerequisites. | ||
|
|
There was a problem hiding this comment.
We are mixing and matching the term "requirements" and "prerequisites" . IDF documentation is written using "prerequisites" I believe we should update the lines 30 and 31 as well to use "Prerequisites for ..."
README.md
Outdated
|
|
||
| > **Note:** For code navigation the [Microsoft C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) or [Clangd extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) can be used for C/C++ language support. By default, projects created with **ESP-IDF: Create Project from Extension Template** or **ESP-IDF: Show Examples Projects** include a template for Microsoft C/C++ extension `c_cpp_properties.json` configuration file and doesn't need to be configured. Run **ESP-IDF: Run idf.py reconfigure task** to generate the compile_commands.json file so language support works. | ||
| 2. Once the project and you open it in VS Code, Set the serial port of your device by pressing status bar icon  or <kbd>F1</kbd>, typing **ESP-IDF: Select Port to Use:** and choosing the serial port your device is connected. |
There was a problem hiding this comment.
This phrase is a bit confusing. "Once a project is open in VS Code" ??
README.md
Outdated
|
|
||
| 19. Next configure your ESP-IDF project by pressing <kbd>F1</kbd> and typing **ESP-IDF: SDK Configuration Editor** command (<kbd>CTRL</kbd> <kbd>E</kbd> <kbd>G</kbd> keyboard shortcut ) where you can modify the ESP-IDF project settings. After all changes are made, click save and close this window. | ||
| 6. When you are ready, build your project by pressing status bar icon  or press <kbd>F1</kbd> and typing **ESP-IDF: Build your Project**. |
There was a problem hiding this comment.
Should we direct the message to the user or to the project? Maybe "When the project is complete" or, " When the code changes are complete", something targeting the code or project rather than the user.
README.md
Outdated
|
|
||
| 21. Flash to your device by pressing <kbd>F1</kbd> and typing **ESP-IDF: Select Flash Method** to select either `UART`, `DFU` or `JTAG` depending on your serial connection. | ||
| 8. You can change the flash method pressing status bar icon  or <kbd>F1</kbd> and typing **ESP-IDF: Select Flash Method** to select either `UART`, `DFU` or `JTAG`. You can alternatively use the **ESP-IDF: Flash (UART) your Project**, **ESP-IDF: Flash (with JTag)** or **ESP-IDF: Flash (DFU) your project**. |
There was a problem hiding this comment.
I would take "you" out of here as well, maybe just "Change the flash method ..."
README.md
Outdated
|
|
||
| 23. To make sure you can debug your device, select your board configuration by pressing <kbd>F1</kbd> and typing **ESP-IDF: Select OpenOCD Board Configuration**. You can test the connection by pressing <kbd>F1</kbd> and typing **ESP-IDF: OpenOCD Manager**. The output is shown in the menu `View` -> `Output` and choose `ESP-IDF` from the dropdown list. | ||
| 11. Before you can debug your device, select your board configuration by pressing <kbd>F1</kbd> and typing **ESP-IDF: Select OpenOCD Board Configuration**. You can test the connection by pressing status bar icon  or <kbd>F1</kbd> and typing **ESP-IDF: OpenOCD Manager**. The output is shown in the menu `View` -> `Output` and choose `ESP-IDF` from the dropdown list. |
There was a problem hiding this comment.
Same here, "Before debugging your device ..." "you" appears a couple of times in the phrase.
Also for the next couple of lines here.
Fabricio-ESP
approved these changes
Sep 25, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Trying to re-write the readme to make sure is enough to get a user jumpstart using the extension.
Type of change
Steps to test this pull request
Read the readme. See if it is easy for a total beginner to get started.
Test Configuration:
Checklist