feature article
Subscribe Now

AI-Powered Documentation Generator and Understander

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?

8 thoughts on “AI-Powered Documentation Generator and Understander”

  1. I’m with Joe!!
    However…
    I once had to write the user manual for a product that I designed. I like to do things well, which makes this task difficult. Cast off any Engineers’ garb and don the garments of Technical Author/communicator. To write a good user manual you need to forget any assumed/embedded knowledge and put yourself in the shoes of the poor first-time user thinking “how do I work this thing?” So, “say what you see!” (No apologies for the !) Tell them what they are looking at. Tell them what task you hope to achieve with your wonderful gizmo and then tell them in easy short sentences how to do it. Easy!!
    Good communication is ALL about your target audience and not an opportunity to show how clever and knowledgeable you (think you) are.

    1. I totally agree — I hate opening a book that essentially starts “As we all know…” followed by pages of incomprehensible BS. I don’t want authors to show me how clever they are — I want then to make me feel clever for understanding what they are talking about 🙂

  2. Documentation should be done “in context”, not merely following arbitrary rules mechanically. Or in this case some rules known only to a program.

    It was assumed that a new MCU was to be designed. Does that mean it will be programmed in C?

    “Logic design” is only known and understood by a rather rare type of person, but is not black magic.

    Rather it is to define the Boolean algebra conditional expressions that perform he evaluation. Next is the debug phase to ensure that assignments are done in the correct sequence and with correct values
    (typically termed “debug”.

    This last step has nothing to do with AI. WORSE YET IT IS A FOREIGN CONCEPT TO THE AVAVAILABLE TOOLS , VHDL, AND VERILOG!

    1. I see this as being two distinct problems — the first is generating high-quality documentation — the second is understanding vast amounts of (often poorly written) documentation. In the latter case, I would welcome a tool that can digest hundreds (perhaps thousands) of pages of poorly written and badly correlated documentation and then answer my questions like “how do I do this?”

Leave a Reply

featured blogs
Dec 2, 2024
The Wi-SUN Smart City Living Lab Challenge names the winners with Farmer's Voice, a voice command app for agriculture use, taking first place. Read the blog....
Dec 3, 2024
I've just seen something that is totally droolworthy, which may explain why I'm currently drooling all over my keyboard....

featured video

Introducing FPGAi – Innovations Unlocked by AI-enabled FPGAs

Sponsored by Intel

Altera Innovators Day presentation by Ilya Ganusov showing the advantages of FPGAs for implementing AI-based Systems. See additional videos on AI and other Altera Innovators Day in Altera’s YouTube channel playlists.

Learn more about FPGAs for Artificial Intelligence here

featured paper

Quantized Neural Networks for FPGA Inference

Sponsored by Intel

Implementing a low precision network in FPGA hardware for efficient inferencing provides numerous advantages when it comes to meeting demanding specifications. The increased flexibility allows optimization of throughput, overall power consumption, resource usage, device size, TOPs/watt, and deterministic latency. These are important benefits where scaling and efficiency are inherent requirements of the application.

Click to read more

featured chalk talk

Dependable Power Distribution: Supporting Fail Operational and Highly Available Systems
Sponsored by Infineon
Megatrends in automotive designs have heavily influenced the requirements needed for vehicle architectures and power distribution systems. In this episode of Chalk Talk, Amelia Dalton and Robert Pizuti from Infineon investigate the trends and new use cases required for dependable power systems and how Infineon is advancing innovation in automotive designs with their EiceDRIVER and PROFET devices.
Dec 7, 2023
63,247 views