Comment by lokar
12 days ago
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.
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)