I have great trouble writing good descriptions of products I build at work (I’m in software). Often I find there are just too many possible ways for me to describe the thing that I get stuck… and inevitably end up with descriptions that simply aren’t very effective. It just seems really hard to flatten an inherently multifaceted or complex thing into a linear narrative.
This topic is slightly different than this post, but there seems to be some useful advice that is applicable to my particular problem. I can “see” what my product is, but can’t really describe it well. Next time I’ll try to focus on what’s important first… which of course sounds obvious, but isn’t how my brain seems to want to describe things.
Is there any other reading out there that people would recommend?
I use the "pyramid format". Conclusion first. Main points with little explanation next. Explanation of main points after that. Details last. That way someone can stop reading at any point and still have a complete view at some level of detail.
Some people find that determining what the conclusion is, is difficult to begin with. Or that there are many conclusions. And, how do you present those details? Chronologically?
A helpful techniques I've picked up (that some people absolutely hate); write down the individual statements on post-it notes. That way you can reshuffle. What would the story look like if A is 'the conclusion'? What if we start off with B? What does it look like if we present the supporting evidence chronologically? What if we present it in a more layered way? ("the colonel couldn't have done it, as on the day of the murder, he was in another city")
Another tip is for the introduction, the lead up to the conclusion; start with listing the facts that are common knowledge, then the fact that raised the question to be answered; then you reach the conclusion. (E.g. Every week, grandma bakes a pie and leaves it to cool in the window. Last week was no exception. But when she went to retrieve the pie, it was half-eaten! The culprit was the cat!) This setting the scene can give the reader some context. In a real-world example, the known facts might include your company's strategy or objectives, underscoring why people should care about your advice.
This approach is also known as the "Minto Pyramid." The website "Untools" has a well-written webpage that explains this: https://untools.co/minto-pyramid/
Nice link, thanks! I was put on to this by someone who had done defence work in their past. They used the "Concept of Operations" for their preferred document style which I also like.
Though this isn't a specific reading, there is a useful habit you can try out: you can start to regularly read well-written newspaper articles, because a focus of written journalism is to break down complex issues into understandable stories. These can provide exemplars for how to approach your own writing.
Consider a recent article in the Financial Times about rising sea temperatures [1][2]. The topic is vast and complicated, which is perhaps relatable to your perspective, yet it's the job of the writer to produce the linear narrative that you mentioned. How does the writer do this?
---
The article presents the key idea up front with a headline ("The dangerous effects of rising sea temperatures"), and then adds context with a sub-headline ("Scientists are increasingly concerned that the world’s oceans are approaching the limits of their capacity to absorb heat").
To ease the reader into the topic, the author then begins by focusing on a human subject by writing: "In 30 years of studying the oceans, Matthew England has learnt to understand their irregular yet constant rhythms — the cycles of wind, temperature and atmospheric changes that interact with the masses of water covering most of the Earth’s surface.
The author continues: "But what he has seen in the past 15 months has shocked him. Global sea surface temperatures have reached and stayed at record levels, fuelling heatwaves and melting sea ice. Temperatures in the north Atlantic waters he has been studying, including around the UK and Ireland, were described last year as “beyond extreme” by the EU’s Earth observation service."
The author later "zooms out" as a narrative technique—similar to the one described in the submitted article—that provides wider context for the problem that the interviewee is describing by presenting cases of natural disasters.
To get deeper into the subject, the author then includes perspectives from various other researchers who study the phenomenon, and then dives deeper into competing theories about the immediate causes behind these environmental changes.
---
So, in your context, you could begin describing how your software tool solves some problem by describing a human user who is facing a specific yet common issue that is frustrating. After the reader then grasps what the problem is, you could write about how your software tool fixes the problem.
But this is just one approach of many. Another author might have taken a "lede-nut graf" [3] approach, where the bottom-line conclusion is put in the first sentence as the "lede," followed by the "nut graf" of a paragraph providing additional context and motivation to read the rest of the article. With this approach, you could skip the focus on a human user, and instead jump right into a sentence that claims your software tool solves a specific problem (especially if the problem is a well-known one).
One of the best methods I've found to get better at a particular skill is to immerse yourself in high-quality exemplars of what you're trying to do. Even without taking notes, you can naturally pick up lessons from what you're experiencing. For this reason, a habit of reading well-written articles could help with your own ability to describe complicated concepts in a way that's more accessible.
This topic is slightly different than this post, but there seems to be some useful advice that is applicable to my particular problem. I can “see” what my product is, but can’t really describe it well. Next time I’ll try to focus on what’s important first… which of course sounds obvious, but isn’t how my brain seems to want to describe things.
Is there any other reading out there that people would recommend?