Documentation is one of those things that people love or loathe. The people who create it typically loathe doing so. The people who use it can go either way depending on how well it’s written.

I was talking to a friend just a few minutes before I commenced this column. We will call my friend Joe (because that’s his name). Joe has strong views on this topic. Joe is less than happy. Joe says he’s spent the past week trying to decipher documentation that was obviously written by multiple people who are (a) extremely knowledgeable and technical, but who (b) have no clue when it comes to understanding their audience and creating documentation that is, in fact, useful.

Apart from the sheer size of the document in question, one clue that multiple contributors were involved is that every aspect of style (including titling and numbering) vary throughout this ~1,200-page behemoth. Just to add to the fun and frivolity, when it comes to even simple things like the bits forming a byte, some of the contributors number them from 0 to 7, while others number them from 1 to 8. The authors often mix decimal and hexadecimal numbers without any indication as to the base. And no one specifies how they store and transmit multi-byte values (i.e., as big- or little-endian).

Joe says another huge inconvenience is that the author of one section will refer the reader to another section (e.g., “See Chapter 7”) without specifying the sub-section. This may be because different people were involved in the creation of each section, and “section X” wasn’t ready while “section Y” was being written (and vice versa, apparently). Joe compares this to a BASIC program full of GOTO statements without any associated line numbers. And things only go downhill from there. As we ended our call, I could hear Joe muttering, “I hate them… I hate them all” (I don’t think he was joking).

Trying to wrap one’s brain around reams of arcane documentation… we’ve all been there (Source: Leonardo.ai)

As an aside (you knew one was coming), having been exposed to technical documentation from multiple sources over the years, I can now take a stab at the country of origin with some degree of accuracy. For example, there’s a noticeable difference between documentation that started life in German and was subsequently translated into English, as compared to documentation that began life in Japanese, was translated into German (there are lots of German-Japanese collaborations), and was then translated into English.

Also, it rarely takes me long to identify documentation that originated in Israel because such works almost invariably have a Shakespearian feel to them. Imagine Patrick Stewart (who starred as the character Captain Jean-Luc Picard in Star Trek, the Next Generation) reciting in deep, rotund tones, “But where are the variables, you ask?” And then immediately replying to himself theatrically, “Why, the variables are over here!” But we digress…

The reason for my waffling is that I was just chatting with Adam Tilton, who is the Co-founder and CEO at Driver.ai

The company’s claim to fame is that they’ve developed an AI that can generate high-quality documentation from disparate sources. Also, it can read, understand, and explain low-quality documentation from incongruent creators.

Although we are only now hearing about this company, this isn’t something that began with a couple of guys and gals in a garage just a few weeks ago. In fact, this business has been around for a while. They’ve been focusing on customer acquisition, and it’s only recently that they’ve come out of stealth mode.

This all started when Adam and his co-founders were working on a problem of their own. This involved an extremely complex piece of lab equipment. To interact with the equipment, they had to go through an API that was written in Telnet. The documentation for the API was a very dense PDF that didn’t give many clues as to how to use the API to drive the machine. As Adam says, “It was just bits and bobs that totally neglected to explain how varying one thing could disturb another.”

In addition to this hard-to-use PDF, Adam had some example script code which, in his words, “was written in MATLAB with zero comments.”

I noted that the only worse thing than having code with no comments was having code laden with comments, but where those comments had not kept pace with evolutions (additions, subtractions, and modifications) in the code.

Adam replied that the only thing worse than no documentation at all is incorrect documentation. He says if you don’t believe this, just go look at the forums on semiconductor websites. But, once again, we digress…

At that time, Adam was using large language models (LLMs) for all sorts of things (think “ChatGPT” to provide a point of reference). This was when he and his co-founders said to themselves, “Hey, how about we feed everything we’ve got into an LLM?”

This essentially allowed them to say to the LLM, “I need to enable an API. Here’s the documentation on the API. Here’s some example code. Here’s the setup of what we’re trying to accomplish. How should we go about doing this? Can you explain to us, in commented Python, what we should do?” Well, you can only imagine their surprise and delight to discover that this worked extremely well, and thus was Driver born.

As Adam told me, “As an engineer, over the course of my career, I have had to learn how to work with all manner of different things. At one company, we had more than 4,000 internal applications. For every project, I had to go and figure out some proprietary system built by some team whose members were long gone leaving only their working code.” I know how he felt.

In fact, there are two aspects to all of this. The first targets the people creating components and/or technologies and/or products. The second targets the people who are using those components and/or technologies and/or products.

Now I come to think about it, there are even more layers to this onion (which may explain why thinking about it is making my eyes water).

For the purposes of these discussions, let’s focus our attentions on the following groups: the people who create electronic components, the people who use those components to build products, and the people who end up using those products.

Example documentation created by Driver (Source: Driver.ai)

Suppose we have a bunch of field application engineers (FAEs) who work for a semiconductor company that’s about to launch a new microcontroller unit (MCU). In addition to documenting the MCU itself, the company will want the FAEs to create and document a bunch of application examples showing how to leverage this device. “Here’s how to enable secure boot,” or “Here’s how to build an activity tracker,” or…. So, the FAEs create these example code applications, after which they write the quick-start guide and the onboarding guide and some example overviews and…

Hold onto your hat because—in addition to writing all the aforementioned documentation—Driver can also generate the demonstration applications themselves (take a moment to think about this).

Now, imagine that a development team wishes to use this MCU and a bunch of other components (sensors, actuators, displays…) to create a product. Driver can read all the documentation associated with all the devices and then answer questions from the engineers designing the hardware and the developers creating the firmware and application software.

This includes eliminating tedious activities, like setup. Driver can say, “Here are the libraries you need to run this” and “Here are the installation instructions for how to get going” and “Here’s the makefile with its configuration variables and the different options you can choose” and… you get the idea.

But we’re not done because, once this new product has been created, it will require its own documentation and its own application examples. Obviously, the hardware and software teams would LOVE to write all this themselves, but I bet it wouldn’t be too hard to persuade them to let Driver do it for them.

Adam showed me examples of all this happening in real-time, and it took my breath away. We truly do live in interesting times. What say you? Do you have any thoughts you’d care to share on anything you’ve read here?