Hacker News Reader

I prefer documentation with sparse text and lots of diagrams and images. It provides the high level context and I can fill in any gaps with a short follow up conversation.

For most people, the high level information is all they really need. The few who need to dig in more can hash out the details in a smaller more effective meeting without wasting everyone else's time.

View on HN

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.

Reply on news.ycombinator.com