I created PicoIDE to be the drive emulator that I’d be delighted to use day in and day out. Part of using something is learning how to use it, and that’s where documentation comes in. Documentation may seem boring but good documentation can make a device a delight to use, even a technically complex one like the PicoIDE.

Think about the last time you used something with poor documentation and how frustrated you felt, and compare it to when (if ever) you used something with good documentation. I can remember several things I’ve used with excellent documentation, some being retrocomputing devices like the Parceiro II, a memory/storage expansion card for the original Amiga 1000. It’s a complex device, and I’m no Amiga expert, but following the documentation made everything crystal clear. One meta-example of a project with great documentation is Material for MkDocs, the framework that I wrote the PicoIDE documentation in. Projects like those were examples I followed when writing the documentation of PicoIDE because I wanted to give users a similar positive experience.

My Philosophy of Documentation

The following is a list of my opinions about what documentation should be. You may not agree with some (or all) of them, but this is what I look for and what I strove for when creating the PicoIDE documentation:

1. Documentation should be available. As in, easy to find and for everyone to view even if they don’t have the product yet. That’s why I made sure the PicoIDE docs were available when the campaign here on Crowd Supply went live. Not only can documentation show the level of care that went into the project (in my opinion), it helps people see what it’s like actually using it. When I’m researching a technical product, the docs are among the first things I dive into: doing so lets me literally imagine what it’d like to be a user of that product. I can pretty quickly pick up on how well thought out something is by reading its manual. So if you’re writing documentation anyway, put it out there: it’s basically free advertising.

2. Documentation should be simple, but don’t let that keep you from going into detail. Start simple: introduce the project or product. I’ve seen so many examples of open source software documentation that don’t even start off with saying what the software actually does! After that, a "getting started" section is a good jumping off point and sometimes all some will ever need in terms of documentation. After that, feel free to ramp up the detail.

3. Documentation can help development. When creating something, do you sometimes have problems figuring out how a certain aspect of it should work in practice? I’ve found that writing up how a certain feature should work as if I was writing documentation for it puts me in the user’s shoes and see things from their perspective. Thinking in a step-by-step manner can help break a project down. Or if you find it awkward to explain how a certain feature should be used or configured, that’s probably a sign that there’s something fundamentally awkward about that feature itself. One of the most insightful things I’ve come across in my career as a software engineer was when I sat down with the technical writer who was writing the documentation for the technically complex piece of software we were working on. She pointed out a part of the application that she had trouble explaining, and when I found myself also lacking a concise explanation, I took that as a sign I needed to go back and rethink how that part worked.

4. Documentation can take many forms. It can be a text website which is great for discoverability, as it will get picked up by search engines. Or it can be a set of videos that walk through the product, which is great for people who prefer to learn that way. I’m much more at home writing than making videos, so I’ve focused on text documentation. All people are different, and that goes for both creators and users of things. Chat platforms like Discord (PicoIDE has a home on the Open Retro Storage Discord) are a great place to get questions answered and are a good companion to documentation, but shouldn’t take the place of it.

5. Documentation is never finished. With all of these points in mind, have I created the perfect documentation? No! Looking at my own docs, I realize I need to add more photos, especially in the getting started section. And when talking to beta testers, I’ve told them to not hold back with feedback. If they run into an issue when setting things up or when trying things on a particularly troublesome machine, I’ll make sure it’s covered in the docs. I’ll probably be adding a troubleshooting section soon, and also a section for contributors, which brings me to my next point:

6. Documentation isn’t just for users. For an open source project, documentation isn’t just for end users, it’s for contributors, especially potential contributors. Making it easy for developers to get started with understanding the layout of the project and building it is a great way to foster an open source community: every potential contributor who hits a roadblock in setting up a build toolchain or understanding the source layout is one who won’t be opening a pull request with a bugfix or new feature. Also, welcome contributions to the documentation itself! If you’re a solo developer like I am, you’re seeing things from only your own perspective. Growing the community of contributors is the key to a thriving project, and documentation can be a big part of that.

Documentation Feeds Design, and Vice Versa

I avoided it for a while, but writing the documentation for PicoIDE has turned out to be a rewarding part of this project. It forced me to think carefully about every feature and interaction, and more than once it led me back to the firmware to simplify something that was too hard to explain. If you’re working on your own project, whether it’s hardware or software, I’d encourage you to treat documentation not as an afterthought but as a core part of the design process. And if you’re a PicoIDE backer, I’d love to hear your feedback on the docs: every question you ask is a sign that something could be explained better. I’ve already updated the docs to take into account questions I’ve gotten from the form on the PicoIDE Crowd Supply campaign page. The documentation, like the PicoIDE firmware itself, is a work in progress, and it’ll only get better with your input.