Hacker News Reader

Comment by megadata | Hacker News Reader

I like the idea. It has it's downsides too but it's way better than either a wall of text or nothing at all.

I know a guy who writes a wall of text. He literally calls it a wall of text. No one reads it and he gets really angry.

Yeah— I hate coming across a doc that’s less like a technical reference, or even a tutorial, and more like a treatise on the philosophy behind their technical decisions. I know it’s a bit controversial, but I find Python’s docs like that. They’re very thorough and great for reading about how the Python interpreter does things, and why, but if you need to quickly reference something about a function or a quick reminder about syntax you infrequently use, they’re miles behind MDN’s JavaScript docs, any of the .NET language docs I’ve used, Elixir’s, and even PHP (though the lack of versioning when I used it seemed dangerous).

If you hit a point in the writing where you say, "the point is" or "long story short" and the scroll indicator is lookin' mighty small, block select everything above and put it into another text editor in case you want to cherry pick a few good bits and just start over.

If you start any sentence to defend yourself with, "It was hard to write, it should be" you the problem.

One of the enduring truths is that most people don't read. We ignore signs that say "don't" and advisories that say "do". If there's reading materials for a meeting, plan to spend the first half trying to recap them.

Tldr: put the tldr at top for goodness sake!

Agree. It's funny how the internet gang reinvented the summary by calling it tldr. But on the other hand tldr is often like a summary of the summary.

Having a good summary at the top at least doubles the usefulness of your document

I've seen "BLUF": "Bottom Line Up Front."

Reply on news.ycombinator.com