Update MicroPython port documentation
Mentors: Matt Trentini & Jim Mussared
https://github.com/micropython/micropython
MicroPython is a version of the Python programming language written specifically to run on microcontrollers, embedded systems, and other computing devices that have minimal resources. It implements the Python 3.4 language as well as a selection of newer features and part of the Python standard library, as well as its own specific modules for interfacing with hardware.
MicroPython is used in a wide range of different areas, including education, medical devices, children's toys, art installations, industrial and scientific equipment, even aerospace. It's suitable for everything from rapid prototyping to final products, and also has a very strong hobbyist/maker following. People love MicroPython because it affords all the benefits of Python, while still giving them great performance and low-level access to hardware features.
MicroPython was a participant in Google Season of Docs 2020, and this was a fabulous opportunity for us to build documentation focused on our developers (i.e. people building and maintaining MicroPython itself). This documentation has been very well received by our core developer community and has become a useful reference for the implementation details.
This time we’d like to focus on user documentation, and in particular documentation for the variety of different ports that MicroPython runs on. This corresponds to all the different CPU architectures and boards, and the various peripherals and features they provide. With better documentation it will be easier for new people to start with the project, for experienced developers to use it as a reference, and for a reduction in the support load - currently handled by a limited number of forum volunteers.
In short, improvements to the MicroPython documentation are necessary to ensure continued growth in the project.
Before considering improvements, it’s useful to review the positives of the current documentation:
While the implementation of MicroPython has progressed rapidly, the documentation has, in places, lagged behind.
In particular, there are a number of ports that are quite mature - even widely used - but have little or no documentation. In order to ensure that these ports remain relevant and usable they need to have reliable documentation.
To ensure MicroPython has good documentation for the main ports, the following ports require documentation to be added:
The Raspberry Pi foundation recently (21st January 2021) released their first microcontroller to great fanfare due to an attractive combination of power and low cost. The RP2040 microcontroller is at the heart of the Raspberry Pi Pico development board and MicroPython has been available for the microcontroller since the day the chip was announced.
While the implementation is approaching feature-complete there is no documentation for this port. As well as the typical port documentation, the Pico will also need documentation for the unique PIO/StateMachine.
The nRF port doesn’t have any documentation; as a chipset with growing popularity, this needs to be created.
There are many (40+) STM32 boards supported but the only current documentation for any STM32 board is for the original pyboard. Documentation should exist for STM32 generally to cover all the boards in the family.
The PyBoard D-series is a recent addition to the ecosystem and requires documentation. While an STM32 board, it’s also an officially supported board and different enough that it requires additional, specific documentation.
The Unix port is also lacking documentation. This port is unique in that it doesn’t target a microcontroller, rather it runs on a Linux/Mac/Windows PC in much the same way as CPython; as such the documentation may take a different form. Many of the common scenarios for using this port are different and are not well documented. This port is also tremendously useful to users of other ports, and also developers working on adding new features to MicroPython.
There are a significant number of improvements needed for existing ports.
The ESP32 QuickRef is relatively new and is incomplete in places, e.g. no mention of DAC or UART. The PyBoard, by contrast, is the most mature and complete but requires updates to guide users to a more consistent way to develop; especially preferring machine instead of pyb where possible.
In some cases, ports require additional documentation or explanations when their features differ (usually due to specific hardware differences). Although it’s desirable to minimise the number of places where this happens, this is a particular source of difficulty for new users when the general documentation doesn't quite cover the port-specific variations.
In general this idea is to better clarify to users that the core of MicroPython is the same across all ports with some differences where hardware significantly differs from the norm.
More specifically, the current documentation contains a QuickRef for each port; these should be consolidated into one QuickRef. When features differ between ports, the consolidated QuickRef should note the differences in ports. Apart from being an obvious document for users to start this will encourage ports to remain similar.
Beyond that, ideas would be welcomed as to how to better document the common and port-specific features. For example, the QuickRefs are becoming quite large, should they be split up (at the risk of not being “quick” anymore)? Should the machine module be documented generically while the QuickRef just focuses on very short examples?
It’s worth collating some port-specific documentation that could be improved:
This project should focus entirely on documenting what is currently implemented. Although it would be preferable to fix inconsistencies between ports (e.g. with code changes), we should focus on describing and documenting these inconsistencies.
Our aim is to improve the documentation that focuses on port-specific variations or documentation that is targeted to functionality only available on given architectures or boards. Other documentation, such as for common APIs, is out of scope for this project, other than where there are relevant port-specific variations.
MicroPython maintainers currently spend significant time answering similar questions on the forum that would often be solved with better documentation. In particular, a good indicator of the success of this project would be that more forum questions can be answered with a link directly to the documentation.
Another good indicator of documentation that people are finding useful is engagement from other community members to improve or extend it. This could be anything from minor fixups, to updates for new features, to entirely new sections.
Separate to, but in conjunction with this project, we will investigate ways for people using the documentation to provide feedback on the documentation, both positive and negative.
Budget item | Amount (USD) | Running Total (USD) | Notes/justifications |
Technical writer audit, update, test, and publish updated port documentation for MicroPython | 5000.00 | 5000.00 | |
Development hardware for the technical writer (selection of different MicroPython boards) | 500 | 5500 | For the technical writer to verify that their documentation is correct, and also to gain experience with MicroPython |
TOTAL | 5500.00 |
Sphinx is currently used to build the documentation, and contributions are made via a PR on GitHub. Whatever improvements are made to the documentation it must be possible for the community to continue to own and easily edit it after the Season of Code is complete.
As a software engineer with two decades experience, I had been helping out with the MicroPython project for the previous five years as a “side project”. More recently, I’ve helped promote its use within my place of employment and now work with the project daily in a professional capacity.
My work in the software domain has been varied, working from embedded devices, through to the desktop and to web development; I enjoy developing at all levels of the software stack.
In recent years I’ve played more of a mentoring role, giving guidance to more junior team members on a wide variety of topics. I've received positive feedback when I've been involved in such a role and, truth-be-told, I've enjoyed it and often learned as much as my mentee.
I was a mentor for Season of Docs (MicroPython) last year and I’m looking forward to - hopefully - being involved again!
I have 18 years experience as a software developer (including 7 at Google, 2009-2016). I’ve been working on MicroPython for the past 5 years working on core functionality, ports, drivers, libraries, and documentation. In the MicroPython organisation I help out with code reviews, sometimes privately reach out to contributors to provide additional assistance, and have provided extremely detailed advice in nearly two thousands posts on our forum. https://forum.micropython.org/
I also have spent a lot of time in the past 10 years lecturing at the National Computer Science School, an Australian summer camp for high school students where we teach electronics and programming. This involves writing (and presenting) course materials. I spent 3 years (2016-2019) working at Grok Learning, where we wrote online courses for school students.
At Google I was in the Noogler mentor program, hosted several interns, helped with the Women TechMakers (formerly Anita Borg Scholarship) program, did mock interviews, was part of the local diversity working group, etc. As a tech lead / manager, I ran a lot of training for my team and related teams.
I’ve been a mentor for Season of Docs (MicroPython) as well as for Summer of Code (QEMU) in previous years.