3 ms·
Another point I want to add is, try to read your own writing from the perspective of a reader. Readers are not yet familiar with the technology. They don't have
by powersnail 4y ago
Another point I want to add is, try to read your own writing from the perspective of a reader. Readers are not yet familiar with the technology. They don't have a mental model like you do. Don't throw minute technical details or really abstract concept at your reader.
Somebody once described to me his note taking system as a networks of pipelines of data input and data output. I'm sure it means something in his mind, but it tells me nothing about his note taking system.
I highly recommend The Sense of Style by Steven Pinker. It goes into detail on how paragraphs and sentences are perceived by readers.
- hinkley 4y agoNot only this, but don’t assume your reader even knows they’re on the right page. Everyone has a different way of breaking down problems, and can click on the wrong link. They need to quickly know whether to hit the back button, before they’ve dumped all short term memory. Tell them why they are here, so they know if they disagree.
- nicbou 4y agoIn journalism, they tell you not to bury the lede. In the military, they call for bottom line up front. The first paragraph of a page should be the confirmation that you are on the right page. By that, I mean that it should explain what and why. "This page shows you how to request a new API key. You must request an API key to..." Then there's the table of contents that guides you to the step you care about.
- nicbou 4y agoThis is really hard. A few tricks: * Read it start to end without making edits. It interrupts the flow. * Read it out loud. * Pass it through Hemingway to find long or complex sentences. * Write common questions on a sheet and see how long it takes to get the answer from your text.