If you are on a team and are tasked with delivering code, record or document your deliverables.
Do this when you finish whole initiatives as part of closing bookends, but also as you make progress at stepping stones along the way.
Every kind of artifact is fair game for a demo: design documents, diagrams, videos, CSVs of data, dashboards, and so on. Be creative, but be mindful that the outcome here is to align others against a sprawling, oft changing technical and product landscape;
Demoing work is about sharing knowledge, not only about showing completed work with a bow on it.
But why document your demos?
Documenting your demos removes the pressure of the "big bang" deliverables and alleviates pressure on your team mates to synchronise to get up to speed. Leaving artifacts allows others to consume in the time that suits them, and picking various mediums, whether that be writing, video, or visuals, allows people to ingest the way that suits them. Experiment and find what best suits your team.
Demos are also useful to regularly present persuasive content and architectural decisions to others. We make decisions every day, and sometimes exhaustion from messaging tools can mean your attempts at overcommunication become white noise to others.
When picking up work it can help to contemplate "how can I demo this at the end? How can I demo this after each chunk?". This is not dissimilar from asking how you might make a system or code easier to test, observe, extend, or modify. Perhaps it's easier to showcase your API by writing a quick CLI, or cobbling together a frontend may give an inlet with your data. Favor lightweight tools; If making a frontend sounds too heavyweight, use something like retool to demo a "live view" of a database table, for example, or draw a diagram during a video. Remember the aim is to be
In the end, value thy readers time. Whatever your decide to present should be quick, concise, and distilled. Think "tiktok" not "The Hobbit". You are looking to convey the kernel of knowledge you have at hand, not the comprehensive breadth of everything that's been accomplished. A good writeup or video should be paired with a space for Q&A, allowing people to ask followup questions. Or, if asynchronously shared, make sure there is a similar place others feel questionable to participate around the material. Engagement means further alignment and a greater likelihood that your audience will remember your message.
Overcommunication is the essence of good advertising. When people complain that they do not (yet) understand the architecture or the conceptual mapping to software and so on, it is because they have not had it drilled into them yet. An essential caveat to this advice is to avoid yanking around the attention of your peers. Take the advice of good MVPs and aim to create "SLCs"; Simple, Lovable, and Complete.
I'll leave you with some practical tools to use:
For recording video and audio of your screen, as well as screenshots:
- cleanshotx
- loom
- screen studio
For sharing articles:
- notion
- coda
- substack
- markdown gists
- markdown in repos
- google docs
For diagrams and live drawing:
- whimsical
- miro
- asciiflow
- (gist with unicode boxes i did sometime back)
- unicode to make boxes
Be kind to your peers, record your demos, and share your gold with your team.