Zachary Kanfer

I'm going to explain how to code your first interface in Emacs.

Many cool ideas require an interface. It allows for data to be displayed, and for more complicated inputs from the user. The user isn't forced to remember what actions they can do, because the interface can remind them.

Unfortunately, making an interface can be intimidating.

• In most programs, you can't create interfaces at all.

• Even software that allows you to create interfaces makes it very complicated. Why would Emacs be different?

• Creating just a normal Emacs package can be intimidating.

Luckily, Emacs makes it easy. Let's begin.

Step 1: Start with a new major mode.

This major mode is the bedrock for all our functionality.

Use define-derived-mode to create your new major mode. Use C-h f define-derived-mode to see the arguments to that function. If you want to create a package called FOO, the first argument should be foo-mode, which names a function that enters your mode.

Step 2: Make a function to enter your mode.

This function will be called to go into your mode. Give it the same name as your mode.

Make it an interactive function so the user can call it by name. Inside it, switch to a buffer named specially for your package, delete everything in that buffer, and call the function we discussed in step 1 to set the major mode to your function's mode, e.g., foo-mode.

Step 3: What would you type to insert the interface? Convert that into code.

Imagine what your interface should look like, and type it out by hand. Then you can write code inside the function from step 2 to insert those same strings. Create some variables to store data, and then insert those variables in the interface when needed.

Step 4: Functionality goes in functions.

Any data manipulation that needs to happen should go through functions. So make some! They can be bound to keys if need be. Those functions should also reload the interface, so call the function from step 2 to redisplay the interface in the buffer.

That's all we need to do to get a basic interface working. You can keep extending your package to have more and more functionality, but you've already created a simple interface! Congratulations! This is the first step to making a useful Emacs package.

You should share your generative art.

In the four years I've been making generative art, I've made dozens of different compositions. Although I worked in secret for much of that time, I more recently started to share my art with others.

Here are some benefits I've gotten from sharing my art.

1. Sharing forces you to finish your art.

When making art, you don't ever have to conclude it. By working on the same piece for a long time, you go in circles, often making no progress at all. Deciding a piece is finished requires you to think about what is important to that work. Doing so strengthens your critical thinking skills.

2. Sharing invites feedback on your art.

When you share your art, you will get feedback. It is extremely motivating to receive praise. You learn what people like, but also what they don't. It's instructive, and helps you get out of your own head.

3. Sharing focuses the selection of generated works.

A single generative art program can generate an unending stream of generated art. You can fall into the trap of generating more and more compositions, hoping that each one will be better than the last. By sharing art, you necessarily have decided which examples you prefer. This, too, sharpens your artistic eye.

If you're creating art, you will get more out of sharing it than you do keeping it to yourself. You'll make better art, and feel good about it.

It's easy to think you should understand a problem entirely before taking any action.

The goal is to fix the problem. So why wouldn't we want to keep digging until we know what it is? We can't start coding until we know what to code, right?

Sometimes we don't know enough to fix it.

It can be better to find out what would help us understand the problem.

If you're looking for your keys in the dark, it is better to go and get a flashlight.

Everyone has examples of times they thought they could push through to finish a task, rather than step back to a more effective starting point. You shouldn't always pause to improve it, but it's useful to consider whether you should. Think of it as a tool in your toolbox, and pull it out when it is helpful.

By waiting to understand before fixing, you can waste a lot of time.

Instead, change the system to give you more information.

Think about what information would help you make the decision, and what would give you that information. Some examples:

1. If you're ending up in an unusual system state, you can add logging on state changes to track down when you got there. That way, the next time it happens, you'll be able to know what happened.

2. If a team is not working well together, you can watch as they go through planning. You'll see how they interact, to see what the issues are, and then can give better advice than if you didn't know what was going on.

3. If you are stuck on a problem, go to someone and see how they solve similar things. Listening to them doesn't solve your problem directly, but it gives you the tools to do so.

Understanding is good, but if you don't understand, change the system to give you more information.

Then you'll understand quicker and better.

Last month, I realized I was spending too much time on my generative art.

I was sitting at my computer, trying to get my artwork to look right. I liked some parts, but the whole piece wasn't coming together. I kept making changes and hoping it would fix everything. It didn't. I eventually became aware that I was going nowhere, and put it aside for a few days.

When I came back from the break, I had so many new ideas.

Working on your art when you're no longer productive wastes time and energy.

Forcing it is understandable -- you want to finish your piece! But you can make it worse. Making uninspired changes can mean adding things you don't like, or messing up parts you do.

Here's what you can do instead.

1. Work on multiple pieces of art at the same time.

When you're actively working on one piece, your subconscious is working on others. When you switch back to another piece, you'll be able to approach it with fresh eyes. The juxtaposition of ideas from two different pieces can be its own inspiration!

2. Use non-productive time to do less creative tasks.

If you're creating your own libraries, this is a great time to maintain them. Consolidate functions from several files into one library. Document your functionality. Make a function more general, or error-proof.

3. Give yourself permission to take a break!

You don't always have to be accomplishing anything! Go for a walk. Read a book. Take a long bath. Your art will still be there when you get back.

If you're spinning your wheels and not getting anywhere, you might as well stop. Only by working with yourself will you create something great.

A few years ago, I realized I misunderstood why I procrastinate.

It's easy to think that I avoid tasks because they're boring and uninteresting. It's a simple answer, which made me suspicious. If it was just boredom, couldn't I work through it? Avoidance is especially bad for me when dealing with work tasks, so I've thought about it most in that setting.

I wanted to be able to get things done without the anxiety of putting them off.

Avoiding the work is more stressful than getting it done.

There was a lot that I wanted to accomplish, but I was getting in my own way. Sometimes, I'd even put off doing things I wanted to do, like going to visit friends. To figure out why, I had to think hard about my behavior patterns.

I realized that for different reasons, I was afraid of doing them.

My emotions towards tasks have more impact on my approach than anything I could process logically.

This was extremely disappointing. I hoped for a simple fix: one I could implement and be done with it. Instead, I found that there would be a lot of hard work ahead. In fact, it's something I still struggle with.

One reason I fear digging into tasks is perfectionism: I worry I won't be able to accomplish them at all, or at a quality I approve of. So I avoid these tasks entirely: by never starting, I keep the hope that I can easily accomplish them.

That hasn't fixed my avoidance problems, but knowing what is going on makes it easier to face.

Our brains mislead us all the time. What I thought was simple boredom led to a realization about why I won't let myself just sit down and get it done. I still need to approach the anxiety I feel when I am uncertain.

The only way to fix it is to work through it. Maybe I'll start later.

One of the best things about generative art is how it can integrate randomness into the artistic process. So don't we want as much randomness as possible?

Of course generative artists use randomness extensively. It's exciting to see surprising results. The art can be completely different each time it's generated. These are good things! But too much randomness causes problems.

• The generated art feels odd, but the artist doesn't know why. It does not make a strong statement.

• The artist has to repeatedly regenerate a work to get a result they approve of.

Making artistic choices randomly abdicates an artist's vision.

Randomness should be a tool, not a crutch used to avoid having a point of view.

For example, pointillist art is a series of dots, and a series of dots is easy to randomly place with random colors. But how could randomly placed dots rival Georges Seurat's La Grande Jatte? Randomness can be used in many ways, but for maximum impact, the artist must direct the randomness.

Deliberate randomness amplifies an artist's vision.

So be careful not to apply randomness haphazardly. For example, randomly choose colors with the same saturation and brightness.

You'll generate works of higher quality in fewer attempts. Limiting your randomness will force you to think about what your art should say, and how the viewer should perceive it. Your art will even surprise yourself -- the artist.

Combine the best of randomness and human creativity.

Your art will be more interesting, with a greater artistic vision.

It's easy to pick on Emacs for being unnecessarily complicated.

Emacs is rather different from the average program. Its has a plethora of keyboard shortcuts requiring memorization. It doesn't use the standard Ctrl-X/C/V to cut/copy/paste. It calls its windows "frames". There are some reasons Emacs differs from other programs.

• It is old. Emacs began in the 1970s, so it predates much of modern UI design.

• It does not have a company determining the direction of the software, but is made by a loose collection of independent developers.

But most importantly:

Unlike most software, Emacs puts the expert experience ahead of the beginner experience.

Most software caters to the brand new user. Many websites display the sign up button in a large, weighty display; the log in link is far less imposing. Intellij pops up a "tips and tricks" window upon opening. Many programs expose functionality only through mouse-driven menus, and don't allow interface customization.

Emacs is different.

Like the cockpit of a fighter plane, Emacs's interface is designed for trained experts. People have been using Emacs for years or decades, and the maintainers generally turn down changes that would conflict with what those users are used to, even if those changes are a better design overall.

So Emacs's prefers to make its current users happy, rather than being friendly to new users.

It doesn't take long to go from a new user to an experienced one. With a little patience, you will experience Emacs as a comfortable, powerful piece of software.

When making generative art, you should always start with code. Right?

Generative art is made from code, so it makes sense to begin by coding. If you're doing anything else, you're wasting time and not actually making art. So coding is the best way to get good art.

In rushing to code, you might find yourself having the same problems repeatedly.

• When you finish coding, the result is disappointing.

• Making a bunch of tweaks to your art, and not being satisfied with any of them.

• Rendering a work repeatedly and hoping one comes out well.

If you don't have a vision of what you're creating, your art will be mediocre.

You'll hope that what you imagine ends up in the image, but you won't be able to tell until the art is coded. It's easy to gloss over details in your head, or be distracted by the concept. Wouldn't it be nice if, before you've written a line of code, you knew you were going to like your artwork?

Before you write any code, do a preparatory sketch with pencil and paper.

It's so common for traditional artists that it's silly to list examples, but Rembrandt, Vincent van Gogh, Leonardo da Vinci, and Andy Warhol all made preparatory sketches. So you, too, can sketch the art you imagine. It's a quick way to see if you like it. I have used this to plan out some of my work, and it lets me rapidly discard bad ideas before spending much time on them.

Sketching your work lets you find art that will work.

Even though sketching a specific picture feels far removed from coding your generative art, it can make your art better.

Programmers should always know what they are doing.

Right? You'd think that people who are well-paid, powerful, and often extensively educated would be certain about what they are making. We don't think of Mark Zuckerberg wondering whether he should create Facebook; we imagine him having a plan to create it, screw his partners over, and become rich. This belief has some knock-on effects:

• Beginners feel stressed that they, unlike "everyone else", have to learn how things work.

• Programmers feel embarrassed to ask for help.

• Even experts can feel anxious when they have to investigate to find out why something works the way it does.

But as a professional programmer, I exist in a state of uncertainty.

Rarely do I know exactly what I am doing, and how to do it.

If I've coded something, I don't ever need to make that identical solution again. So I almost never have do the same thing twice. Also, I spend a lot of time debugging code. By definition, I don't know what the solution is! if I did, I would move ahead and implement it. This is hard to emotionally accept -- I know I struggle with it. As much as I logically know it to be true, it's hard to feel it in my bones.

It's not easy, but it's empowering to accept that it's ok to not know.

Really take the time to think about what that means.

All you have to do is make progress. You don't have to know what the solution is upfront. Even finding something that doesn't work has ruled that out! Isn't that much better than not knowing that?

You're not all-knowing. But no one else is either.

Can you think of anyone that knows everything about programming?

I can't. So why should you be the only one held to those standards? It's unfair of you to hinder yourself with that belief. Let yourself free, and see how much more you accomplish.

Config files should be as readable as code.

There's a lot of discussion about how to make code readable, but rarely about how to make configuration files more readable. Programmers focus on code because that's the more exciting part of solving problems -- code is dynamic and powerful. Configuration files don't process data; they are data!

But this leads to configuration files being hard to read.

• Grouping of similar attributes is often ignored. The language doesn't encourage good organization the way programming languages do.

• Rarely is there explanation of what a setting does, or why it's configured that way. Sometimes the configuration language doesn't have comments, so there can't be this added explanation!

• Many configuration languages aren't Turing complete, and are painfully limited, without variables, loops, or functions.

• Setting names are often painfully abbreviated or obtuse.

• Tooling around config files is far more limited than code. "show usages" commands are common for functions and classes, but not for config values. It's hard to clean up configs without knowing what is unused.

Config files change how the whole program runs, so they're just as important as code.

And if config files are that important, it's vital they be readable.

What good is a config file if it's unreadable? The program using it might work for the moment, but it will quickly become unmanageable. Software that is difficult to read is quickly fixed. Config files should be treated the same way.

And it's not especially hard.

You have to care.

Treat your config files the same way you do your code. Think about someone unfamiliar with the config reading it for the first time. Will they have the proper context to understand?

One way to improve config files is to order the lines to group similar attributes together.

Your configs will be more readable. When you come back to a project, you'll be able to quickly understand whether two values are related, because you left a comment. You'll see all related settings in a single block, and know how the software will run.

This will make your software more reliable.

Sometimes, I know exactly what I want my generative art to be.

But usually, I'm lost. I stare at Emacs for a long time, not knowing what to do. I get frustrated, like I'll never come up with anything good.

Here's a different way to think about it.

I find that when I'm frustrated, it's because I'm jumping into code without having a real idea. It's hard to code something without knowing what I'm coding.

So first come up with an inspiring idea, then start coding.

I start with these categories, and generate ready-to-code ideas from them.

1. Juxtaposition

Place two different things next to each other. Some examples:

• One color fighting another.

• One hundred tiny dots and one big one.

2. Minimalism/maximalism

Take something as simple or complex as you can go.

• A single loop.

• Ten thousand dots of the same size.

3. A physical process

You'll find happy accidents when you are inspired by physical things.

• Close your eyes. Look at the afterimages you see.

• Pick up a pencil and paper. Doodle some shapes.

4. The real world

The real world is full of randomness. Use it!

• Clouds floating across the sky.

• Be inspired by the wind.

5. Abstract concepts

Pick an adjective, idea, or phrase. What would that look like?

• Fade into black.

• Winding.

Use these categories for making your own challenges, and inspire yourself.

To become an Emacs expert, learn where to find information about Emacs.

Over the fifteen years I've been using Emacs, I've learned a whole lot about it. My packages have over 50,000 downloads, and I've presented at EmacsConf 2020. I co-organize EmacsNYC. In that time, I've found the best place to ask questions about Emacs...is Emacs!

Here's how you can ask Emacs questions.

1. The Emacs tutorial -- C-h t

Emacs's built-in tutorial is incredibly well-written. It takes you from knowing nothing all the way through undo and redo, autosaving, and window management.

2. Show functions and variables -- C-h f, v

Press C-h f and type the name of a function to view the documentation for that function. C-h v views a variable's documentation. If Emacs's source is installed, you can click on a hyperlink to go the function's source.

Emacs's documentation is comprehensive. It explains what a function does, and what its arguments are, but the documentation viewer even also tells you what keypresses that function is bound to! This works not only for built-in key bindings, but any you have added.

3. Show what function is bound to a particular keypress -- C-h k

To ask Emacs what will happen when a certain key or series of keys is pressed, type C-h k, then the key you are interested in. This brings up the same documentation from C-h f, with the same detailed information.

4. Show what keys are bound in the current buffer -- C-h b

If you don't know what you can do in the current buffer, ask Emacs! C-h b lists all the functions currently bound.

If you have a multi-key binding, you might not know what comes next. After beginning any prefix, press C-h to show bound keys after that prefix. Even an Emacs pro will learn something new with C-x C-h.

5. View documentation about active major and minor modes -- C-h m

To see documentation for the modes that are currently active, ask Emacs! C-h m displays the mode descriptions plus bound keys.

If you have Emacs questions, start by asking Emacs. It knows best.

A mechanical keyboard is a kind of computer keyboard. Instead ofa rubber mat inside, it has individual switches. This keyboard might be right for you.

Here are some reasons why.

1. Typing is better on a mechanical keyboard.

With a rugged construction, typing is solid and satisfying. Keys travel with comforting stability, unlike other keyboards' mushy feel. You'll know you're using a well-crafted tool.

2. Unique hardware options.

Mechanical keyboards have a wide range of hardware features:

• Keyswitch options, with different force to press, sounds, and tactility.

• A volume dial.

• Fewer keys. A keyboard without a numpad or Fn buttons is smaller.

• Improved ergonomics, like each hand having different angles for wrist comfort. Or arranging the keys in a grid, rather than copying the design of an 1800s typewriter.

3. Unique software options.

Mechanical keyboards have powerful firmware. Spacebar can be control when held down, but backspace when double-tapped. Pressing the F and J keys together can turn on capslock. Control can toggle, so even after being released, the next keypress is a shortcut.

And you control all these options.

4. Visual customizability.

Mechanical keyboards have many options for customizing their look. You can swap keys with different colored keys, clear keys, and keys that glow in the dark. Keys exist that don't have the English alphabet printed on them -- but instead Japanese writing, flags, or blank keys. Some keys are shaped like trees, superheroes, and animals.

Some mechanical keyboards also have LEDs under each key. These lights can be programmed in a variety of colors and patterns.

5. You can build it yourself.

Some people get enjoyment out of assembling things themselves. That's one reason IKEA is popular. You already know if this applies to you.

Whatever intrigues you about mechanical keyboards, there is almost certainly one that's right for you.

I hope you find it.

The most common way to end an improv scene is with a sweep edit.

Sweep edits indicate the end of one scene. Being an unusual movement, they are rarely mistaken for an action inside the scene. However, sweep edits do have a few downsides.

• They are artificial, a meta action outside the world of the show. They distract from the reality built inside the scene.

• They are foreign, only existing inside improv. They can be distracting to new audience members.

• They are mechanical, rarely being able to be themed to the show or scene.

Sweep edits are the most boring way to end a scene.

They don't add anything to the show beyond "this scene is over".

Improv is a form of theater. An improv show is more interesting when it's more theatrical. But sweep edits are not theatrical. I saw an improv show by a group called Centralia. Patrick McCartney stood upstage, wearing a chair on his head.

He stood there, unmoving and unnoticed, for two full scenes.

Until another actor was declared Queen. Moving to the center of the stage, he pulled the Queen out of one scene and initiated the next as a knight pledging his loyalty.

That's theater.

And you can make your shows similarly compelling.

You can pick different kinds of edits. Whether you use tag-outs, transformations, narrative edits, or simply begin a new scene, you'll add a striking moment and surprise the audience.

Your shows will be more energetic by not having the downtime of a sweep edit. You'll perform fascinating narrations to put images in the audience's mind. You'll stand out from other improv shows merely by being different.

Getting rid of sweep edits will transform your improv show.

If you want to make shows that are worth coming to, you have to care enough to do something special and unique. Otherwise, why would anyone see your improv show? Getting rid of sweep edits is one way to make your show memorable.

A few years ago, I printed my generative art for the first time.

Generative art begins digitally. It is a secondary task to get the art printed, involving more time, cost, and effort. Why get it printed, when you can post an album of your art and get instant feedback? Here are some commonalities I see when seeing generative art online.

• There are a bunch of copies of the same piece.

• The colors are chosen randomly. They aren't related to each other.

• The artist focuses on the algorithm used.

The artist hasn't thought about what makes the piece visually appealing.

When I printed my art, I realized I wasn't going to pay to print a bunch of copies of the same piece, so I had to select the pieces that worked best. After looking at what I liked and didn't like, I made changes to the art to make it better.

I wondered why I didn't do that same winnowing down process when posting my art online.

Printing your art forces you to consider your artistic vision.

Think about what you want the art to be, and how you can get it there.

Your art will improve. You'll find ways of choosing colors that look good together. You'll shape randomness to give you targeted results. You'll make art that is visually appealing even to viewers who have no idea how it was created.

The more you think about your artistic vision, the better your art will become.

And whether or not you actually print it, keeping the option in your mind will improve your art.

You can give more technical talks than you do.

And you should. Being able to educate people is powerful. You'll convince people to follow your lead. And you can't explain something if you don't understand it, so giving talks will teach you to organize your thoughts clearly.

Unfortunately, public speaking is intimidating.

• Do you think you don't have anything to say?

• Are you afraid people won't be interested?

• Do you worry you aren't an expert?

These fears are understandable. Here's how you can make a worthwhile, interesting talk.

1. Commit to only a five-minute talk.

A short talk removes much of the pressure -- no one expects a world-changing event. You can prepare quickly, so give several to get over jitters. And even if it is rough, it's over fast.

You can talk before a technical event, at a work lunch, or even at an evening with your friends. Most event organizers have to beg speakers to volunteer.

2. Pick something you learned.

Thinking about what other people want is a foreign, unfamiliar process. So pick something that helped you, like a programming language peculiarity or hidden feature of your shell. If it's interesting to you, it will be to others. Take five minutes and list ideas. If you take time to think, you'll get something worth talking about.

3. Outline the talk.

The hard part -- getting started -- is done! Now outline it. Explain the problem, the solution, and how it solves the problem. You don't need to write down every word, just general ideas.

4. Give the talk.

Speak casually, like you are talking to a friend. You don't need to be an expert. Just explain this cool thing you know about to some people that hadn't heard about it.

Giving talks will level up your skills. You'll think more clearly. You'll convince others to follow your lead. You'll be more confident, because you've proved to yourself you deserve to be.

My early generative art used direct pixel values to place elements. I rendered it in a larger size, and nothing moved.

I stared at my computer, confused why my carefully placed shapes sat awkwardly in the upper left corner. I realized the locations were hardcoded inside a small frame; in a larger canvas, they were in their original positions. I had to update every single pixel number. But they were still hardcoded.

If I had expected my art to change, I would have made it flexible.

Flexible art is better art.

If it's rigid, a lot of code must be modified to make simple changes.

When your vision changes, you'll have extra work to change your art. It can make your art not take advantage of randomness, which can give amazing surprises. Worst of all, you'll keep subpar art to avoid fixing it. Flexible art gives you the ability to think at a higher level, treating your functions as new building blocks.

Here are some ways to keep your art flexible.

1. Extract everything possible into a function or variable.

Change a single variable and watch it affect disparate places across your art. Newly created functions can be used in other art pieces. Your code will be better documented by coming up with names for these values.

2. If you need a value inside a range, calculate the fraction of the range.

This would fix the mistake I made in hardcoding pixels. Rather, multiply the canvas width by how far across you want the point. Changing the range also changes the calculated value. Color values can also be calculated inside a range. Angles can be based off a starting angle, so you can change the angle the entire shape rests at.

3. Know your art framework. You don't know what you want to do unless you know what you can do.

I wrote functions to graph polygons, before finding out Quil already has them. Look through your art libraries, and you'll find new, useful features.

And unlike my early experiences, you'll find new options, and be inspired for better art.

People say you should leave Emacs's default keybindings unchanged.

Emacs is unbelievably customizable. Nearly any key can be changed. But there's advice given to rely on the defaults; they have been honed over years and years to be the best for everyone.

Forget that.

Emacs is better when it's tailored to you specifically.

I have never used C-z -- at least, not on purpose.

C-z minimizes the Emacs frame. I would hit it by accident, surprising me when Emacs disappeared. For nearly a decade, I left it bound, hoping I would eventually get used to it. After all, the default keybindings had been carefully planned out. Right?

Right. But they have not been planned out for you.

Your needs are not the average user's needs, and your solutions should be different too.

So change your Emacs to work with you.

You can rearrange keybindings to make more sense to you. Or override existing keybindings with improved functions. M-c on my Emacs goes to #'capitalize-dwim, because that's better than #'capitalize-word. I've replaced C-M-f, C-M-k, and other s-expression navigation functions with smartparens.

Some other ways you might want to configure Emacs:

• Disable the toolbar and menubar. Take the screen space back.

• Hide the startup screen. Make your Emacs boot right to *scratch*.

• Don't use the custom file. Configure everything with Emacs Lisp.

If you believe that everything in Emacs was designed to be unchangeable, you're missing out on the best parts of Emacs.

After all, it was designed to let you change it.

People believe that the quality of generative art code doesn't matter, because it only exists to generate the artwork.

This is an understandable belief. When an artist makes generative art, they are looking at the image produced. If they art that comes out is good-looking, that's "good enough". But there are some issues that come out of this belief:

• It's hard to modify the code.

• When you reread the code, it's hard to understand.

• The code isn't reusable.

Your generative art would look better if your code was better.

Better code lets you do more with your art.

When code is more readable, it's easier to understand. And when the code is understood, it's easy to modify. I recently went back through five years of my generative art, and I was shocked at how difficult some of the code was to modify. Conversely, there were some pieces where I was able to make significant changes with little code, just because the code was well-factored.

You have to make code readability a priority, because it won't happen on its own.

One way to do this is to pretend you don't already know what is going on, and write your code so it's clear to a new reader.

Your code will get clearer and more descriptive. You'll name things better, so you will always know what those things do. Your helper functions will be used in later art, saving time and expanding possibilities. You'll easily modify your code to do new, creative things.

If you don't care about the quality of your code, you're limiting your art.

Better code makes for better art.

It's easy to throw together some code and make something that looks ok. But the more experienced you get, the more you'll want to do complicated things, or build on top of prior art. Better code will help you do that.

Over the years, I've given and watched a lot of technical presentations: project demos, hackathon presentations, or even talks at meetups like Emacs NYC, a meetup I organize.

I've realized that a lot of talks dive into deep technical details too quickly, leaving behind people that have a different background from the presenter. In my talks, I use a three-part framework to make sure that doesn't happen, called Why/What/How.

1. Why

Begin by motivating the whole presentation: why did you do the thing we're talking about? What is the problem we're trying to solve?

Talk about how previous solutions didn't work, or if the situation changed, so the solutions no longer applied. The goal of this section is to motivate the project you're talking about. This helps justify any decisions made later; you can point to something in the Why.

2. What

This is a high-level view of the solution. You don't want to get into the technical weeds.

Especially strong when given from a user-focused perspective, this explains what the vision is for the project. If you have a demo, this is the place for it.

3. How

This part, containing technical details, is the least important part of the talk, and should be cut down if the talk is going long.

Is that surprising? Didactic presentations -- where the goal is to teach people to use a technology -- are rarer than you might think. A presentation is often strongest when it gives people the ability to discuss the technology with others. If someone really wants to understand every detail, they can follow up.

This framework begins with a high-level overview of the problem, zooms in to see the solution, and ends with a micro level of how the solution works. This is intentional; a listener can more easily follow if they don't have to jump back and forth between disparate complexity levels.

This framework even has a built-in ending. Go back to the problem you started with in the Why and reiterate how the solution fixes that. Then, the audience is able to follow you, because you've prevented them from getting lost.