Bryan’s thoughts on #CircuitPython2021

With eyes squarely on the rest of 2021, as the tradition goes, I offer my thoughts here on what I’d like to see for CircuitPython as a language and community during this year. This year I’ve chosen to focus on documentation. Read on to hear more about my thoughts in excruciating detail, or if TLDR, skip ahead to my Rules for Good Documentation.

Features vs Documentation.
There are no shortage of Spicy New Things on the horizon and I’m always happy to navel gaze at what possibilities await us, and the inspiration that these provide is important, but new and amazing doesn’t always mean New Things.

I’ve previously brought up a few thoughts on what I’d like to see, but they’ve always mentioned documentation in one way or another, so I’m going to take this year’s post to focus on my hopes for documentation in general and as it applies to CircuitPython

Documentation is the lifeblood of an open source software project. Yes, one can make due without it, reading source code to understand how things work, however one way or another to have a robust and fruitful open source project requires continual help from community members. Paid developers and contributors are core to the project and most times the project owes its existence to these people and those who pay for their time, however the community surrounding the project and their contributions are necessary for the project to grow and thrive. Bugs need to be fixed, PRs need to be reviewed, issues triaged, features perpetually on the back burner need attention, community supported, the list goes on. Even when the people paid to work on a project can do these things, more people helping is always better.

What does this have to do with documentation you may ask? Why do I care so much about documentation and why have I chosen to write about it? In short because it’s meaningful for me. Early in my programming journey, good documentation enabled me to feel like I was doing something that I cared about, and further filled me with a sense of wonder and possibility. Documentation is important to me because it can help ignite a similar spark in other folks.

Story Time
Rewind to some time in the early 2000’s. Evanescence’s “Bring Me To Life” was annoying parents of angsty teens everywhere, cargo pants were briefly acceptable in public, and The Fedora began its journey from pop star accoutrement to icon of bafoonish, unrequested chivalry. Despite these hardships, I had just landed my first job that involved programming and was encouraged to study up on “.NET” (pronounced ‘dot net’), Microsoft’s latest attempt at world domination.  While I had learned the mechanics of how to program, .NET and it’s C# (‘see sharp’) was entirely new to me, so I was faced with learning how to do stuff I ‘already knew’. This part was easy enough because I knew what questions to ask because it was clear that i needed to learn the fundamentals that exist in every programming language. What I had not expected was how this simple task would be expounded upon by the Microsoft Developers Network.

MSDN is among other things where Microsoft made it’s documentation available and so learning this new language lead me there. Time has passed and my memory of then is more a feeling than facts, however once I got through learning what was needed for my immediate task, I was enticed by all of the other documentation that was relevant but not directly to my immediate project. It seemed like anything I could want to do with a computer was right there, ready to be explained. Fast forward a day or so and I had written a very dumb chat bot that connected to IRC (Discord’s ancestor) and responded to commands.

It was empowering, seeing that I had done something because I wanted to, not because i was told to. I was able to take my small but meaningful bit of success and knowing how little of the available documentation I had used, I knew that I had found a huge treasure trove of not just documentation but of possibilities.

Not everyone is going to have their life changed by good documentation, but I’ll do my best to enable that possibility for as many people as possible until the cows come home.

Bryan’s Arbitrary Rules for Good Documentation

1. Exist. First and foremost, any effort at documentation, be it code comments or examples are infinitely better than the documentation that never exists. Anything that helps people understand and learn how to use CircuitPython is welcome and encouraged. 10 points to Grifflepuff for the next PR that adds an example I haven’t gotten to, or for a fix or clarification of my work or the work of others.

2. Be Accessible. For as much as I kvetch about CircuitPython documentation, there is actually a lot of documentation that exists. The main issue I’m hoping to address is to make it easier to locate the documentation that exists and to reduce duplication and separation between the various sources.

3. Don’t Suck. This one is subjective but documentation should be good, should explain clearly, and not be overly reliant on contextual knowledge. Simply re-stating the name of a function and calling it a day is a waste of the author’s and every reader’s time. I’m more than a bit guilty of this one, however I try to remind myself that while documentation seems at times to be “extra” on top of good working code, that documentation is worth much more than the characters it is made of.

Explaining what code does and how it can be used not only informs the current user, but it makes the code more usable by more people than a poorly written alternative. Beyond that,  I’m 110% certain that projects with good documentation have an easier time expanding their user base since it empowers advocates to spread the good word with working examples. It’s a lot easier raise interest by saying “hey, try this thing, here’s an example” than “try this other thing. It works very well but it’s going to take some homework to understand it.”

4. Be Discoverable and Inspirational. Also subjective but important. The prior three points make for quality documentation that I would be happy to put my name on. My work at Adafruit mostly achieves this, however it’s not all that it could be. Discovery in this context is a buzz word I picked up while doing ten to fifteen at various startups. In human it means something like “being self promotional and marketing”. A classic example is of music discovery. You go to see your favorite band and arrive in time to see an amazing opening act that you’ve never heard of that is now your new favorite band of all time. You did not go searching for that band, you were simply in a place where you could find something that you like just by the fact that it was available to be found by being associated with something you already knew and liked.

Amazing documentation will lure you in by telling you how to do something, and then will sit back as you find and learn about the rest of the possibilities on offer by the rest of the documentation. Something as simple as listing just the names of functions or classes along with making it easy to see a quick summary without opening a new tab or window makes it trivial to learn about the scope of possibilities that the code presents. Execution matters here; you don’t want to overwhelm users with details and information that they don’t care about, but that should be balanced against making what is on offer visible and attractive.

That’s my spiel for CircuitPython in 2021. TLDR: Documentation is important.