Hacker News Reader

Comment by lokar | Hacker News Reader

As a senior engineer I spend a lot of time reviewing and approving technical designs, PRDs etc.

Over the years the amount of basic copy editing I have to do has really grown. I sometimes feel like I’m removing 20%+ of the text. And that was before LLMs.

View on HN

Ask your team to make their documentation at least 30% shorter just before sending. I don’t remember where I first I read this advice for writing code, but it’s been part of my workflow for several years. It’s an arbitrary number, but it forces you think how to make things simpler. I apply the same principle when packing for travel or hiking.

I once ended up helping (a bit) editing a book (with chapters written by various co-workers). My main contribution was deleting whole chapters. And telling others to make it 50% as long.

For better or for worse my team has standardized on using Miro for technical designs and diagrams. It's a lot easier to visualize the system in a diagram than it is to talk about it in prose.

I think it's important to choose the right medium for communication though. Some things just need to be written out concisely.

Mermaid has been great for a similar reason. For example, you can render a mermaid diagram inside a PR description on GitHub.

Comes in handy when describing a state machine or the flow of data.

Yeah! I recently discovered those, mainly because Claude seems to love mermaid diagrams, and Cursor has a renderer for it (it's not great but it's pretty easy to port to Miro)

Reply on news.ycombinator.com