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.
I recently purchased tickets via SeatGeek and was provided a link to one of these barcodes, which accepted as a querystring parameter an access token that seemingly had a long expiration attached to it. It was hosted on “downloadmytickets.com”, which doesn’t look legitimate and caused me to do this same type of analysis to see how it all worked. Whether or not this was a way to bypass the “security” to enable sale via third parties, or just a very untrustworthy-looking official domain, I don’t know. But in the end it worked fine at the venue. Definitely more stress involved than I would have liked though.
Yes, these systems are getting more popular recently, I believe they are typically being run by large ticket broker platforms.
I don't know about the specific site you mentioned, however the large broker platform Automatiq runs a number of domains like this, where they effectively proxy the original ticket token, recreate it with TOTP just as in this article, and display it to any user who has the right link in a similar format to how TM displays it. They advertise this service as "Transferless Delivery" to their ticket reseller customers. The main Automatiq one is called "secure.tickets".
It reduces work for sellers, because they never even have to transfer the tickets out of their Ticketmaster account anymore. Of course, it's horrible for buyers because they have no idea whether the random website link they were sent is actually going to serve them a barcode corresponding to a real ticket or not, or whether the site will be up, and they have no rights to the ticket as far as the primary ticket issuer (TM) is concerned, buyers don't even know the name on their own tickets.
Seatgeek and StubHub seem to be aware of these systems because of how closely they work with ticket brokers, and just coach customers to accept them if they are from any of the domains known to them. See https://support.seatgeek.com/hc/en-us/articles/2074030716443... the Automatiq site is called out specifically on that page.
Been a few decades, but I was in a similar situation and came up with a similar approach. Run the select first and then swap in an update or delete.
If the query was somewhat involved to determine what to delete, I’d write the select query to just select row IDs of rows for deletion (assuming a simple primary key), then wrap that with a “delete from table where ID in (select ID from …complex query…)”.
I have a similar need but for the FHIR[1] spec, which has its own way of describing RESTful http endpoints that serve FHIR data.
I was looking into how this works for inspiration, and it seems like the work of inferring the OpenAPI definition from recorded requests/responses is handled by the har-to-openapi nodejs library [2]. Is this by the same team? If not, kudos for packaging this up in a proxy -- seems like a useful interface into that library.
I did that for the exact same problem on the same model car earlier this year, but gave up after trying a few places that all said the same thing (including the dealer). Glad to see this post though… now I know I’m not the crazy one.
I would expect a _good_ car (no maintenance issues, new gas, newer battery) to go at least a couple months without being driven and not have any issues upon starting it up.
The average car in average condition should go around a month without being driven. Anything less than that either means a battery nearing the end of its life, not getting charged, or a parasitic draw somewhere.
We have a 10 year old Honda Odyssey that we keep just for long road trips and it has gone 3-4 months without being driven with no issues. I usually do try to fire it up every 1-2 months just to make sure the battery gets a charge and to avoid long term storage issues around oil and belts and other parts that degrade.
Thanks, that's good advice. Luckily we've burned a tank or so every road trip (every few months) but I was wondering about that and whether it was good for gas to sit so long.
I park up my hilux for a year at a time, sometimes, and it Just Starts. Sure, it’ll take three attempts with a cold, damp engine and a sluggish battery, but it has yet to let me down.
Had one of those, too, and used to hide it in a pint of Guinness for a laugh. Dropped it in the sea a few times. Accidentally melted it slightly in a small housefire. It lived on after I moved on to a t68i as an SMS gateway for my home server for my one-man proto-Twitter.
Wow, I have a 2012 Mazda3 and have the same problem, which only really surfaced during the pandemic when I stopped driving my car regularly. The dealer said it was just a normal level of drain (even though it would die in just 4 days of non-use) and I should get a trickle charger. Which I did, and is annoying, but is something that I can deal with. I’m not sure if I’m willing to disconnect my remote entry to see if this fixes it, but I’m glad others have seen similar behavior because it really bugs me that the mechanics would just shrug and not really diagnose why this was happening.
Great job, this is a fun concept that is well executed.
I was going to add Geocities, but I was surprised to find out that it is still available in Japan. Anyone have insight as to why Yahoo kept it alive in that market?
Yahoo! Japan was a joint partnership of Yahoo! and SoftBank. From what I could tell while working at Yahoo!, Yahoo Japan was able to use whatever software they wanted from Y!, but whatever they developed wasn't accessibly by the rest of Y!
So, they had their own installation of geocities, and didn't need to take it down. Yahoo auctions is also big in Japan, but was killed everywhere else. (Edit: change was to is)
Atroyn is referring to @Pinboard the person, who is critical of free bookmarking sites and has a history of buying them for cheap when they eventually fail.
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?