Documentation is absolutely the most important part of the creation process. Anybody who creates things to be put out into the world does so with the desire to provide for their fellow man. As engineers, we do this by providing well-written, concise and data-rich documentation to our end users so that they may take our work and make great things with it. 

Given the imperative nature of documentation, does hardware documentation have to be this hard to use?

This issue quickly became bruising for me during my own process of developing some embedded system-based projects. As I looked into acquiring the potential pieces of my project and how I would program these devices, it quickly became obvious that I was spending way more time reading PDFs than I was working on bringing my design to reality. 

Eventually, I hit my breaking point when I realized I was spending three hours of Control-F-ing — Command-F for you uncivilized folk — through documentation per every line of code that I was actually writing. Added to this was my lack of confidence in what I was developing because the documentation had zero lines of code and required me to make massive assumptions.

As I looked further, I realized that this matter of extremely difficult documentation seemed to mainly be a hardware problem. As someone who has written and used tons of documentation for software, one primary difference I saw between hardware and software documentation is a principle I like to call “show, don’t tell.”

Consider something as monolithic as the open-source Android codebase released by Google. A very cursory look at the documentation shows us that the common API — that 95% of app/OS that developers will use — is exposed through very simple, approachable examples. The documentation doesn’t dump the source code on you, pat you on the back and say good luck, and neither does it give you tons of detail in plain English sentences that try to describe extremely abstract concepts. 

It shows you what you might be trying to do. In hardware, this is hardly ever the case.

We can see this in something as widely famous as the documentation used by certain MCUs. If you wanted to use the inbuilt ADC function said chip offered, the documentation would give you a singular, very hard-to-read compound sentence that has multiple values in it that do completely different things. Here, the guessing game starts. 

If at this point you decide to look further into the documentation to gather a deeper understanding of how the ADC works so that you can make a good guesstimate of which value you’re supposed to use, good luck. The absurdly large document only mentions the pin you’re trying to read up on two times and one of those times is in a massive diagram that makes the Aztecs look like tryhards.

Further, we can see a more malicious pattern in a lot of hardware documentation where the manufacturer provides more useful and detailed information only for their more expensive boards while providing the bare minimum in a way that’s very tedious to use for their cheaper products that use the exact same central parts.

The manufacturer also provides next-to-zero actionable tutorials for the cheaper products while making highly comprehensive examples for the higher-end ones. Even in this case, users of the cheaper board are unable to use parts of the information provided since most of the critical information is abstracted away with the additional parts that are put onto the expensive board.

This information also tends to be the hardest to digest and implement, so it makes the creation process even more difficult since it becomes almost impossible to spot quirks and implementation details for the cheap boards.

Increasing the barrier of entry to access necessary resources acts as a very precise double-edged sword. Keeping users from being able to realize the full extent of the product they’ve bought forces them to buy more expensive products from manufacturers that are more easily accessible. Further, this aspect forces creatives from poorer rungs of society to either overspend or be pushed completely out of the sphere. 

This makes engineering resources and experiences even harder for these marginalized communities to access.

All this is to say that the process of making documentation comes off as an altruistic act but can oftentimes be boiled down to its reality as an ouroboros snake designed to make you solve your problems by spending more money. Perhaps it’s time for us to stop letting these companies get away with insufficient documentation practices and take matters into our own hands by creating information sources for users by users.

Prarthik is a junior in Engineering.

[email protected]