Technical content and a-ha moments

I have been learning to reflect on the question "where is the a-ha moment" as I produce technical content, both in video and text form. The "a-ha moment" articulation was unknown to me until recently, but when the point was explained to me you could say I had an "a-ha" moment myself. Meta indeed. I have become more focused on showing the outcome of a project upfront, particularly in technical guides. If a visual representation of the outcome is available -- a video or an image -- I shall use that instead.

Earlier today, I was working on a piece of content and I thought to myself: if the only part of this guide that someone reads is the first few sentences, are they going to be enticed to keep following? Would they have the information they need to understand whether the rest of this article is for them? To set the bar even higher, consider this: what if the reader is skimming the content, as one so often does when evaluating whether a piece of content will help them solve their needs.

I like to explain directly in the introduction of a guide what that guide will discuss, either in bullet point form or a few succinct sentences. I add line breaks liberally to make the content easy to skim. If available, I'll add a video or an image at the bottom of the introduction with the idea in mind that I want to show, not tell what I am going to guide someone through doing.

This applies not only to text content, but video, too.

Earlier I was preparing to record a video and I was thinking about the sequencing of that video. My mind drifted toward a concept that was introduced to me in the opening lecture of the online FastAI machine learning course. The instructor wanted to show what you could do before explaining every little detail. I, too, want to do this in my videos. I thought to myself earlier today: I should put the demo at the front-and-centre.

Don't bury the lede. Concisely summarise the key points, then delve deeper. With this mindset, I find myself trying to refine the "a-ha moment" a bit more in my head. Often, that moment doesn't come before writing a piece. It comes during the writing phase or after an editorial review. Indeed, one of the best pieces of feedback I have received is, to the affect of "we need to make the a-ha moment clearer." As a reader, too, I appreciate it when the real utility of a product or software, the exciting part of a product launch, or the goals of a technical guide are concisely and prominently defined.

Tagged in writing.