Taken from https://twitter.com/theburningmonk/status/1714159389496479856?s=20 and worth a summary in not-so-Twitter-format.
๐ฆ๐ฒ๐น๐น ๐๐ต๐ฒ ๐ฝ๐ฟ๐ผ๐ฏ๐น๐ฒ๐บ, ๐ป๐ผ๐ ๐๐ต๐ฒ ๐๐ผ๐น๐๐๐ถ๐ผ๐ป
Like that scene in The Wolf of Wall Street where Di Caprio asked Jon Bernthal to sell him a pen. First, create the demand, then supply the solution.
Sell the problem to the reader. Help them understand why itโs a problem worth solving. If the readers are not interested in the problem you’re solving, they won’t care about whatever solution you propose, no matter how good the solution is.
Be explicit about what “good” looks like
Explain what a “good” solution means to you and your rationale before diving into describing your solution.
Finish off with the ๐๐ฟ๐ฎ๐ฑ๐ฒ-๐ผ๐ณ๐ณ๐ and what context your solution worked in (e.g. high throughput API).
Everyone’s mileage is different and your readers likely care about different qualities to you. Communicating WHY you think a solution is good and WHEN it’s a good fit helps readers understand your way of thinking and judge whether or not it’s also a good fit for them.
Also, it’s important to define this “goodness” up front. It helps combat cognitive biases that we all have, such as confirmation bias. Defining โgoodโ ahead of time helps keep us honest with ourselves.
๐๐ฒ๐ฒ๐ฝ ๐ถ๐ ๐๐ต๐ผ๐ฟ๐, ๐ธ๐ฒ๐ฒ๐ฝ ๐ถ๐ ๐ฐ๐ผ๐ป๐ฐ๐ถ๐๐ฒ
Don’t linger with your words, remove paddings and fluffs. Attention spans are short and precious
๐ฃ๐๐ ๐๐ต๐ฒ ๐ฏ๐ถ๐ด ๐ถ๐ฑ๐ฒ๐ฎ ๐๐ฝ๐ณ๐ฟ๐ผ๐ป๐
Eric Evans once told me that he regretted introducing ubiquitous language and other big DDD ideas in the 2nd half of his book. Most people only read the 1st half and think DDD is all about the repository & entity patterns.
Another reason for putting the good stuff out first is to help you start strong and grab ๐ฒ๐ฎ๐ฟ๐ป the reader’s attention so you can spend them on the nitty-gritty technical details later. The reader’s attention is a currency, and you do have to earn it first.
๐ฃ๐ถ๐ฐ๐๐๐ฟ๐ฒ ๐๐ฎ๐๐ ๐ฎ ๐๐ต๐ผ๐๐๐ฎ๐ป๐ฑ ๐๐ผ๐ฟ๐ฑ๐
But not all pictures are created equally, so choose them wisely. And don’t overdo it
Mind the “curse of expertise”
Always remember that you are the expert in your domain. When you share knowledge & experience, you need to be mindful of what assumptions youโre making of the reader. In the immortal words of Simon Sinek, always start with why (see tip no. 1ย
Be honest
Goes without saying.
Use simple language
The goal is not to look smart, the goal is to convey your big idea to the reader with minimal loss of precision. Complex sentence structure gets in the way of absorption. Hemingway is a great tool to help with this.ย https://hemingwayapp.com
Harald's Random Stuff 