How to: Writing (communication, blogging)
➡️  See also my [engineering-management list](https://github.com/charlax/engineering-management#writing)

- [Undervalued Software Engineering Skills: Writing Well](https://blog.pragmaticengineer.com/on-writing-well/)
  - From the HN discussion: "Writing a couple of pages of design docs or an Amazon-style 6 pager or whatever might take a few days of work, but can save weeks or more of wasted implementation time when you realise your system design was flawed or it doesn't address any real user needs."
- [Sell Yourself Sell Your Work](https://www.solipsys.co.uk/new/SellYourselfSellYourWork.html?te20hn)
  - If you've done great work, if you've produced superb software or fixed a fault with an aeroplane or investigated a problem, without telling anyone you may as well not have bothered.
- [The Writing Well Handbook](https://www.julian.com/guide/write/intro)
  - Ideas — Identify what to write about
  - First Drafts — Generate insights on your topic
  - Rewriting — Rewrite for clarity, intrigue, and succinctness
  - Style — Rewrite for style and flow
  - Practicing — Improve as a writer
- [Write Simply](http://paulgraham.com/simply.html), Paul Graham
- [Writing is Thinking: Learning to Write with Confidence](https://blog.stephsmith.io/learning-to-write-with-confidence/)
- [It's time to start writing](https://alexnixon.github.io/2019/12/10/writing.html) explains why Jeff Bezos banned PowerPoint at Amazon.
  - The reason writing a good 4 page memo is harder than "writing" a 20 page powerpoint is because the narrative structure of a good memo forces better thought and better understanding of what's more important than what, and how things are related.
  - Powerpoint-style presentations somehow give permission to gloss over ideas, flatten out any sense of relative importance, and ignore the interconnectedness of ideas.
- [Programming and Writing](http://antirez.com/news/135), Antirez
- [Writing one sentence per line](https://sive.rs/1s)
- [Ask HN: How to level up your technical writing?](https://news.ycombinator.com/item?id=31859040). Lots of great resources.
- [Patterns in confusing explanations](https://jvns.ca/blog/confusing-explanations/), Julia Evans
- [Technical Writing for Developers](https://css-tricks.com/technical-writing-for-developers/)
- [Some blogging myths](https://jvns.ca/blog/2023/06/05/some-blogging-myths/), Julia Evans
- [George Orwell's Six Rules for Writing](https://infusion.media/blog/george-orwells-six-rules-for-writing/)
  - Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
  - Never use a long word where a short one will do.
  - If it is possible to cut a word out, always cut it out.
  - Never use the passive where you can use the active.
  - Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
  - Break any of these rules sooner than say anything outright barbarous.
- [Blog Writing for Developers](https://rmoff.net/2023/07/19/blog-writing-for-developers/)
- [7 Common Mistakes in Architecture Diagrams](https://www.ilograph.com/blog/posts/diagram-mistakes/)
- [Why Blog If Nobody Reads It?](https://andysblog.uk/why-blog-if-nobody-reads-it/)
  - Blogging forces clarity. It makes you structure your thoughts, sharpen your perspective.
- [Specificity: A weapon of mass effectiveness](https://longform.asmartbear.com/specificity/), A Smart Bear.
  - Swap generic words for specifics to make your text clear, powerful, engaging, and even funny.

Guides & classes about technical writing:

- [Documentation Guide — Write the Docs](https://www.writethedocs.org/guide/)
  - Principles
  - Style guides
  - Docs as code
  - Markup languages
  - Tools
- [Technical Writing One introduction](https://developers.google.com/tech-writing/one), Google
  - Grammar
  - Active voice
  - Clear & short sentences

![Write like an Amazonian](./images/amazon_writing_rules.jpeg)

> If you’re overthinking, write. If you’re underthinking, read.
> – @AlexAndBooks_