Stenography - A smart codebase documenter combining AI & code parsing | Prod...

Hey all, I'm Bram, founder and creator of Stenography. In the following wall of text, you'll be able to understand the philosophy of Stenography, why it is valuable, and what's next.

# Why Stenography? Why now?

With the introduction of GPT-3, Codex and other machine learning models at scale, we are entering a world where machines no longer have to be programmed meticulously to supply value to humans.

We can train adaptable models to solve moving target problems, and make our lives easier and more fulfilling as new problems replace old in the infinite game of universal complexity.

# Creative Content

I've been in the business of content creation around creative coding for a couple of years now and the process always looked something along the lines of:

1. have an idea 2. sketch out idea on paper 3. write code for idea 4. get stuck and go to Google for answers 5. return to number 3 until project is complete

In addition to that workflow, there is the workflow of sharing with the project with others (because no one is realistically going to sit there and read your code):

1. decide what concepts are important and which are not 2. distill information into the necessary 3. write/record/speak 4. mess up or get stuck 5. edit 6. return to number 3 until finished

The thing is, that's a LOT of work. Doing both workflows requires a good understanding of TWO audiences: humans and machines.

## Humans Don't Talk Machine

The core value addition of Stenography is that it decreases the amount of time that you as a human need to speak machine. Speaking machine is a hard thing to do. It's like juggling numbers in one's mind, while also thinking of a step as a series of smaller steps. "What did this subroutine do again?" "How do I split this string by character index?" "Why is this null??"

Documentation (in theory) helps humans tell other humans what they told a machine to do. The reason for this is that there are MANY ways to solve the same programming problem (check out 'Comparison of server-side web frameworks' on Wikipedia).

We write documentation to convey to our fellow human beings what the code written for the machine is doing.

But why can't the code tell us itself? Why do we need to serve as author AND translator?

# The Two Parts of Stenography

Stenography broadly works on two layers: the parsing layer and the explanation layer.

## The Parsing Layer

If you're familiar with Kolmogorov complexity, you'll know that not all code patterns are created equal.

Some code is MUCH more dense than other code, and a lot of it comes down to the author that wrote the code, their mindset around code abstraction and obfuscation, and how long it is until lunch.

The goal of the parser layer is to find sufficiently complex code blocks up to the level of expertise that the AI can break down into a helpful explanation. (wait, what? ._.)

In other words, the parser layer uses my and other developer's expertise in their native coding language (JS, Python, C, etc.) to capture the idiosyncrasies of the code and determine where the RIGHT code is for the AI to step in.

This requires human creativity, and an expert who can grasp where humans and the AI tend to get stuck/bundle functionality of code.

## The Explanation Layer

The explanation layer requires another strategy. The first (and most important) question to ask: What IS a good explanation? The answer: it depends.

An explanation is only good IF the target audience understands it AND can act upon it. The explanation cannot be too simple or too complex. It cannot be too short, or two long. It must stay focused, but it must supply external resources when necessary.

This part of Stenography is fun because not only is it more subjective, it requires an understanding of the psychology of the reader. In addition, the AI often just doesn't want to cooperate, so cajoling it to return a helpful explanation is much more art than science.

Both of these layers serve the overall goal of Stenography: developer productivity.

# Developer Productivity

Finally, the most important part of designing Stenography for me was to create a tool that integrated seamlessly into the development workflow.

Too often tools will make you go out of your way to supply value, or forcibly change the habits of their host.

Stenography Autopilot API runs automatically on save in the VSC extension. It writes CodeLenses and gives developers the option to add the comment to the file if they want to. It reads multiple languages, and tries to stay out of the way as much as possible, while supplying a nice buzz when the AI not only correctly describes code, but teaches the developer something new.

Most importantly, Stenography gives developers a jumping off point to get back to doing what they actually want to do: WRITE CODE.

If you made it this far into the essay, download the extension and try Stenography on your own code!

To end on an anecdote: I git pulled a file I've never seen before, opened it in VSC for the very first time and was greeted by a wall of unfamiliar code. I held in my heart the hope of adding to it, leaving it in a better place than I found it, but it stared back cold and imposing.

After a moment, I saw little silent gray lines populate the file like stars on the outskirts of a metropolitan area. Little islands of respite, giving me a smooth runway for take off. Little patches of knowledge, flattening the friction of the learning curve of something new.

I sat back in my chair, relaxed my shoulders slightly, and thought to myself, "Finally, Automatic Documentation."

---

Bram