←back to thread

69 points mtlynch | 1 comments | | HN request time: 0.289s | source
1. jcalx ◴[] No.44379817[source]
I generally agree with these points but I sometimes find "do X, not Y" suggestions too prescriptive to be helpful. Compelling phrasing should be context-aware and mindful of how users actually use the product, what their pain points are, and what they find useful.

Largely I take issue with the use of metrics. "Create events 10x faster" reminds me of the "put hard numbers in your resume" advice that people blindly follow — it's not a useful description to use here! When I go into XYZ Calendar and create a new event by copy-pasting fields, I don't think "hey I wish this was 10x faster" but rather "I wish I didn't have to do this". Announcing the feature as "Duplicate events instantly" cuts right to the heart of the improvement without splitting hairs of "I can do unnecessary work N times faster".

For "fixed a thread deadlock that froze the UI for up to two second when creating a new file" vs. "we sped up new file creation, so you can now create a new file in under 20ms, a 100x speedup from v1.2" — if the new file stutter is a common complaint, we can celebrate this by acknowledging the flaw and its fix. "Creating a new file is now instant after we fixed a thread deadlock bug" conveys that (1) a common user annoyance is now gone, (2) we recognized that it was an annoying bug, and (3) we put in the work to fix it. And no "100x" in there — we didn't speed up an annoyance, we got rid of it entirely.

Of course performance metrics aren't always bad — "Gleam JavaScript gets 30% faster" announcement is great! But compiled language speedups is something that users care about, and not something we want to abstract away (e.g. by merely saying "faster" or "better"). Here, putting a concrete number in the title and letting it speak for itself is absolutely the right choice.

Context is everything for making writing compelling. On that note — Style: Towards Clarity and Grace [0] is the best book I have read on writing clearly and effectively.

[0] https://en.m.wikipedia.org/wiki/Style:_Lessons_in_Clarity_an...