Performative art is an experience created through the interaction between the artist and participants. While software is written to solve a problem, we can elevated it to performative art if carefully consider the interactions with our participants.

As software artist, our participants include fellow software artist, product owners, designers, operations and most importantly, our future selves. We are our own biggest consumers of what we produce as we are the most likely maintainers of our own code.

Personally, I don’t have much room in my head and I’ve already forgotten the code I wrote last week. This is why code is read much more often than it is written.

Knowing I will forget code I write today by next week, what artifacts shall I leave for myself next week? How do I make sure my elegant and simple design is continued into the future?

Leaving breadcrumbs

The simple answer is we need to document our software development process. We don’t need to remember anything. We have computers for that! We just need to be diligent in writing everything down and putting it where it can be found.

• Explain why this software exists
• Describe the domain problem and draw an overview diagram
• Write self-documenting code
• Publish roadmaps
• Breakdown features into tasks
• Record decisions and progress made to tasks

With good findable documentation, it becomes easy for everybody (include yourself) to not only understand the purpose of the software, but also gives them a headstart on how to modify it.

The meat of the matter

After a participant has discovered the documentation, give them the meat of the matter. Show them the next level of detail.

• Write tests not only show correctness but also help the reader understand how to use the software
• Describe the types (use TypeScript declaration file or JSDoc), even when using an untyped language
• Add useful seams
• Expose logs and metrics for observability
• Write and answer fully anticipated questions
• Describe open decisions and their possible directions

Demand a better world

After one practices leaving breadcrumbs and getting to the meat of the matter for themselves, it becomes the new norm. Software is simply so much easier to work with.

When it comes time to evaluate software written by others, look for breadcrumbs they left for themselves. How are they attempting help you understand their code?

This is why I read the documentation for all software library, frameworks and services I can get my hands on. This is art that feeds me.

However, sometimes when looking for breadcrumbs, they are not found. We should demand (nicely) for better documentation. Show them how much time they will save not having to personally explain it repeatedly and how better documentation would show off the simplicity of their software.

Do you want to create art? You’re in luck, Battlefy is hiring.