Hacker News Reader

Comment by tibbar | Hacker News Reader

I have been known to author twenty-page documents in a fit of caffeine and have rarely been pleased by their reception. Circulating such epics is an office crime of sorts.

However, I think the quality of a document - and the time it takes to understand it - is less about the length, and more about how it's organized. Sometimes a document will have many useful attachments, clearly labelled, that a reader can optionally review if it's helpful. If the document has a good narrative flow, motivation, and structure, then someone can get the point quickly and skip around as they wish. Making documents very short is one way to ensure readers can follow easily, but there are ways to make it work for long documents, too.

View on HN

I completely agree, it all hinges on the quality of the document.

I really don't mind twenty-page docs when they are well-structured, have a clear drill-down from less details to more details through the relevant parts, documents where I feel are guiding my reading towards the important bits I need at the time, and making me comfortable to get into the weeds when I feel prepared enough by understanding what's the general point of the document. It's actually pleasant to read those.

The issue is: almost nobody has (or puts in) the time to properly edit a twenty+ pages document to make it pleasant to read, I've been guilty of that too in the past and do understand it usually comes from having so much of the context in one's own head that it gets lost taking the view of someone reading all the context for the first time.

I've strived to be better at it for years and it isn't an easy skill to learn but in a larger organisation it's immensely valuable to save everyone else's time.

> almost nobody has (or puts in) the time to properly edit a twenty+ pages document to make it pleasant to read

That's why technical writers and editors exist.

They exist, and are very valuable, but I've never worked at a company that employed even one full time technical writer. If I go on a caffeine bender and write the 20 page doc OP described, nobody is coming back around to clean that up for me. At best some peers might tell me "hey, great effort there, but could you cut the word count by 75%?" Access to full-time professional editors seems like a luxury of very large organizations.

I don't know. I work for a B-series startup and I'm a docs engineer.

I was thinking about the article's idea of having a lot of tags to organize all the little documents, and I think I see what they're missing. Often, the most important part of writing is providing a coherent structure and mental model for a complex, messy system. Tags are not a good way of doing that. If you only write small documents and then have a hodge-podge of tags to group them together, you seriously risk missing the forest for the trees. People need to understand how complex systems fit together, not just read short descriptions of all the engine parts.

"Assigning homework." I've heard it called.

If you must write 20 pages of text, split them up into eight documents that are all reasonable.

Reply on news.ycombinator.com