Go Down

Topic: An actual community improvement process (Read 277 times) previous topic - next topic

simoncc

I was curious about how Arduino gathers input from its users after looking through the "Wire" interface.

It's not a great interface; one example might be that there is no possible user control over the full i2c address byte, which can come in handy for devices that have odd features. This is the case with the Honeywell ABP pressure sensors, as when they're in sleep mode, to use the partial wake addressing feature one needs the R/W bit unset for an i2c read. Another might be that returning a transaction object might be a better way of structuring this library, at least for professional programmers; such a view can tell if begin() has been called again for a different transaction, collect bytes for a particular request, and hold bus settings that can be reasserted when a mode for a peripheral is needed again.

Its documentation is also quite poor, both in its format (there is no formal return type listed alongside the functions, and a typeless explanation is sometimes buried in the text) and in its coverage (Wire.requestFrom() does not explain if it is synchronous, and returns only when the read has actually completed, or if the user should sleep/poll with Wire.available() to check).

The documentation page itself is hard to use; there also isn't an obvious link back to the module documentation from the function documentation, and the other functions in the module aren't listed in full on the function pages.

Given that this is one of the most widely used bus protocols, its kind of a shame that this is what we're left with. So many people depend on Arduino for professional projects now.

Python has its PEP process: https://www.python.org/dev/peps/pep-0001/#what-is-a-pep. And Java has its JCP.

 And yet we only have this forum to put ideas in to. What about a steering council? Or formal proposals? Or elected members? This could channel expert technical advice from community members into a structured process.

pert

I was curious about how Arduino gathers input from its users
Arduino employees regularly attend/organize events where they interact with Arduino users in person. They definitely use this experience to get an idea of the user experience.

Certain Arduino employees monitor specific sections of the Arduino Forum which are in their particular areas of work.

I monitor all posts on all sections of the Arduino Forum and do my best to relay any reports of bugs that I can reproduce on to the places where the people on the Arduino team who can resolve them will see it. In the case of feature requests and things I can't reproduce, I will not be able to do this and it would make sense for the person with the request or issue to report it directly to Arduino (see next paragraph for an explanation of how to do this).

I would say that the primary way for the community to provide input directly to the Arduino developers is by submitting issue reports or pull requests to the appropriate repositories on GitHub, where Arduino's source code is hosted and their development work is done. However, this requires a different style of communication than we usually see here on the forum. Here on the forum, we can have rambling discussions, provide support for someone's project, etc. If someone makes a post that is essentially a duplicate of 100 others that came before, that's fine, we'll help them out. The GitHub issue trackers must be very well organized and focused. The time the developers waste dealing with vague, invalid, or duplicate issues is time they won't spend making the improvements and bug fixes we all benefit from. So before you submit an issue report or pull request to the issue trackers it's very important that you make sure to use the correct repository, search for previous issues/PRs on the same subject, and also make sure to be very clear in your communication. You can find a guide to doing this here:
https://github.com/arduino/Arduino/blob/4c9da50e57030aebd4320fcc24e3f497f504b663/CONTRIBUTING.md

For this reason, it makes some sense that the Arduino Forum is more of a place for the Arduino community to discuss things, rather than a way for the community to communicate with the Arduino organization.

There is also the Arduino Developers Mailing List, which is sort of a middle ground between the Arduino Forum and the GitHub repositories:
https://groups.google.com/a/arduino.cc/forum/#!forum/developers
That is not an appropriate place for people to ask for help with their projects. However, it is a bit more "chatty". People from the Arduino organization do monitor the mailing list, though they may not necessarily participate in all discussions.

It's not a great interface
One thing to keep in mind is that once a standard API for something fundamental like the Wire library is established, it causes major issues for large numbers of people to make any breaking changes to that API. For this reason, sometimes we are stuck with suboptimal decisions made long ago.

Another thing to remember is that the main focus of Arduino is to be friendly to beginners. For this reason, an easier interface may be considered preferable to a more complex one that is more powerful or efficient. The two are not always mutually exclusive though. I think Arduino has been able to create something that is both easy to use but also allows us to do very advanced things. Of course, there is always room for improvement. These are only general points. I'm not necessarily arguing about any of the specifics you mentioned.

Its documentation is also quite poor, both in its format (there is no formal return type listed alongside the functions, and a typeless explanation is sometimes buried in the text) and in its coverage (Wire.requestFrom() does not explain if it is synchronous, and returns only when the read has actually completed, or if the user should sleep/poll with Wire.available() to check).

The documentation page itself is hard to use; there also isn't an obvious link back to the module documentation from the function documentation, and the other functions in the module aren't listed in full on the function pages.
Reporting specific issues or suggesting improvements to the documentation is a very valuable contribution to the Arduino project. I agree that there are things that need to be improved throughout Arduino's documentation. Generally, for library documentation I would recommend that you create an issue in the specific repository for that library. However, in the case of the Wire library there is no specific repository because a different version (but with a compatible API) of the Wire library is bundled with each hardware package. In addition to being the place to report issues with the Arduino IDE's GUI code, the arduino/Arduino repository acts as a catch-all for issues that don't fit in any of the other repositories:
https://github.com/arduino/Arduino/issues
Please be sure to read and follow the contributing guidelines first:
https://github.com/arduino/Arduino/blob/4c9da50e57030aebd4320fcc24e3f497f504b663/CONTRIBUTING.md

Go Up