Hacker News new | ask | show | jobs
by mmarq 1722 days ago
Do you find it easier to learn something new from pictures and bullet points or from a long-form document?

That kind of documentation is not necessarily bad, but it depends heavily on context, which is not always shared across readers. So when the author and those they talked to are not available anymore, it quickly becomes useless.

Don’t get me wrong, I don’t think people should write War and Peace. Usually a good 2-3 paragraph introduction improves the quality of a document/email significantly. There you can provide the context that is necessary to fully understand the pictures and lists and diagrams you add after.