Howdy,
I'm really keen on technical documentation and have been producing a book of notes ... see ...
http://esp32.com/viewtopic.php?f=2&t=390
In my opinion, the most important documentation areas that need to be covered are "architectural". While the ESP-IDF is a vitally important component in the development of ESP32 solutions, the documentation covering the growing array of rich APIs isn't currently easily consumed. An API description is not the same as an architectural or programmers guide.
For example:
Code: Select all
setAccelerator()
setBrake()
steerLeft()
steerRight()
initializeEngine()
stopEngine()
getSpeed()
... may be necessary APIs for controlling a car but they aren't sufficient in order to learn to drive. For example, these APIs don't describe that one shouldn't setBrake() and setAccelerator() at the same time not should one stopEngine() while the return from getSpeed() > 0.
I fancy myself as a programmer and when I am in the midst of writing APIs for others to use, the last thing on my mind is documentation. By the time I have finished writing my APIs, I am usually so "buried" in how they work that I fail to consider how they will appear to others who try and use them. This is a shame as the purpose of me writing APIs in the first place was never to "get them working" but was to allow "others to use them".
What I would suggest, if I may be so bold, is to get folks from the community who are technically skilled but at a variety of different levels (novice, practitioner, expert) and for each area of ESP32 function ... give them your first pass at the docs to read and then have them collaborate to write up their experiences on comprehending the material AND attempting to build something from it.
Do this on-line (public or private or semi private). Make sure each of the functional areas is not too big ... i.e. not THE WHOLE OF ESP-IDF ... but for example "I2C" or "SPI" or "RMT" or "BT GATT" or "BT GAP" etc etc.
As the comments come in ... do NOT be tempted to respond to them in the electronic media ... this exercise is not a forum alternative. Instead, update the docs with the responses to the comments and cycle around again. It is vital that the documentation become the source of knowledge and not the documentation + forums.
In summary ... I think we don't need more new types of documents ... we need to consider content in the existing documents and make it focused on consumability ... and make it consumer driven.
