The double edged sword of open source development.

It is wonderful that with open source software you can go and look and see exactly how something is written, but all too often developers then use this as an excuse for not writing documentation.

When help is requested, too often the response is just to “look at the sourcecode”.

I appreciate that when coding for fun or at least where you don’t have the pressure of someone demanding documentation of the interface between your closed-source software and your clients’ own development that it’s easy to skip this work, that your code is such high quality of course others will find out what they need just by reading; This is true to some extent, but definitely relied on too heavily.

Take my recent experience with ESPHome, part of the Home Assistant ecosystem. On the one hand it’s an awesome project, allowing non technical users to build and manage custom firmware for their IoT devices from their browser with just a few snippets of YAML. Only a few years ago trying to build C++ code for embedded devices would have been a complex setup including cross platform compilers etc.

There are a selection of components available in the main distribution and systems in place to either pull in components from additional repositories or even build a custom component by writing small snippets of C code within the YAML file itself.

Technically awesome, but documention massively lacking. For example, under the information about certain component types it gives you an example of how to build your own class to implement a sensor. What the example fails to show however is what includes you need to actually make this code compile. Is that a big issue to solve, no. Would an experienced developer know that you need to have an #include, of course. What is not documented at all is how esphome.h is dynamical generated.

This leads to some very odd behaviours, for example if you start writing your own external component, you are implementing a text_sensor. If you just add the repository, but don’t actually reference text_sensor in your config to read the value back, your code will fail to compile. You can correct for this by adding some extra code to a python script, but that isn’t referenced in that part of the docs.

A much better example is this article about how to use ESP-NOW https://randomnerdtutorials.com/esp-now-esp32-arduino-ide/

It gives clear information about what the capabilities and use cases are, the code examples are complete and it explains each section clearly