4 ms·

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 literal

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.

chefandy 2y ago
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).
readthenotes1 2y ago
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!
- megadata 2y ago
  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
- D-Coder 2y ago
  I've seen "BLUF": "Bottom Line Up Front."
hinkley 2y ago
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.

chefandy 2y ago

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).

readthenotes1 2y ago

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!

megadata 2y ago
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
D-Coder 2y ago
I've seen "BLUF": "Bottom Line Up Front."

hinkley 2y ago

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.