platformio / platformio/platformio-docs
Inconsistencies in tutorial documentation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 285
- Forks
- 357
- PR merge metrics
- No merged PRs in 30d
Description
This post follows this one where there is still some unsoved points: https://github.com/platformio/platformio-docs/issues/33#issuecomment-426641785
10.a
11. some are fixed but not all of them the STM32Cube tutorial does not have up to date screenshots: https://docs.platformio.org/en/latest/tutorials/ststm32/stm32cube_debugging_unit_testing.html
23: unsolved.
(24) New one: The note : "2 sec delay is required since the board doesn’t support software resetting via Serial.DTR/RTS"
is missing on this ESP-32 tutorial, isn't it ?
https://docs.platformio.org/en/latest/tutorials/espressif32/arduino_debugging_unit_testing.html
So, to summuarize:
(A) equivalent 10.a:
When opening nRF53-DK tutorial it says to install j link drivers BEFORE beginning the debug session tutorial
However when following the steps of installing drivers, see:

However when following the steps of installing drivers, it says to start debug session while the newcommer doesn't have a clue of how to start a debug session (an additionnal instuction should be added on this line, to explain how to start debug session).
(B) eq. 11: The screenshots of STM32Cube are not up to date, the icons does not include the new ones.
(C) eq. 23: in nRF52-DK tutorial the text says to add some functions to the existing code, but the whole code is new.

A solution for this inconsistency:
So to correct this problem, in the section writting unit test you can create previous paragraph (between writing unit test and "Test cases can be") accompanied by a source code that manages hello_world strings, And then you can explain "but as we cannot easily verify the content we need unit testing." And only after this you can say in the next paragraph: "we need to ADD four functions etc..." to test our code.
And then the source code which tests the strings. (the source code will be adapted to the previous).
(D) eq. 24: The note : "2 sec delay is required since the board doesn’t support software resetting via Serial.DTR/RTS"
is missing on this ESP-32 tutorial, isn't it ?
https://docs.platformio.org/en/latest/tutorials/espressif32/arduino_debugging_unit_testing.html
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the unresolved points linked from issue 33 and the nRF53-DK, STM32Cube, nRF52-DK, and ESP32 tutorial pages named here. Check each reported instruction, screenshot, code example, and missing note against the current tutorials. Done means the four inconsistencies are resolved consistently and the affected documentation is updated.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, embedded-iot
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100