[_x5ft]

I can't help but feel this essay is literally 100x longer than it needs to be for the point it's trying to make. This sort of long-winded, redundant writing seems to have gone out of style a long time ago.

[grrdotcloud]

Maybe hard work has gone out of style?

Yesterday I poured over two companies documentation. About 200 pages of their API docs only to find:

Dozen of typos. Errors in versions. Conflicts in examples. Broken examples.

I barely invest in this much reading but this time I did because I was trying to deliver and sure enough I'm able to benefit our entire product because of this effort.

[GavinMcG]

By the way, and only because your comment suggests you care about detail and will find this valuable: it’s “pored over” unless there was a liquid you were dumping on them.

[projektfu]

It's lousy documentation but it makes great coffee.

[grrdotcloud]

Thank you. I didn't know that was the correct spelling.

[echelon]

> pored over

Let's change this. That's disgusting. Literally.

[vsareto]

It’s hard to not be lazy in today’s corporate environments. You simply don’t get much for putting in the extra effort.

Hard work needs incentives. Companies want you to light that fire yourself so they don’t have to pay extra. It’s why I’m not curious about anything work-related (plus it’s hard to be interested in CRUD apps after a decade). Even if I was, I’d give the benefits to myself and not my company.

[KnobbleMcKnees]

Do you have examples of 200+ page API documentation that doesn't have any errors or broken examples?

Sounds like the law of small errors to me:

https://www.maa.org/external_archive/devlin/devlin_4_00.html

[imran-iq]

Django docs come to mind

[KnobbleMcKnees]

https://docs.djangoproject.com/en/4.2/ref/class-based-views/...

> from article.view

Broken example due to typo.

I'm being facetious but it's actually easy to find them because their are typo PRs open in their GitHub.

Hopefully demonstrates the point though: the law holds.

[smokel]

Perhaps I am a bit too cynical here, but I think that it is harder to criticize a long-winded article than a short bold statement -- thereby making it slightly more comfortable to publish. For a critical reader, it takes a lot of effort to read the entire article, then check that its flaws are not nullified by some additional arguments, etc.

[williamstein]

> "Believe it or not, I tried to make this essay as short as I could. But its length at least means it acts as a filter. If you made it this far, you must be interested in doing great work. And if so you're already further along than you might realize, because the set of people willing to want to is small."

I scrolled up and down quickly through the essay, and the above was the very first thing I randomly read.

[_x5ft]

I find that quote rather condescending. It’s also an excuse in disguise.

[331c8c71]

"You are special (if you made it so far)" part is a cheap manipulation imo.

[carlossouza]

Although I enjoy reading his essays, yes, they tend to be longer than usual.

I wonder whether he uses an editor to provide constructive feedback before publishing it or just writes and clicks "publish."

Interestingly, I found that point missing: people who do great work usually have editors/mentors/advisors to help them along the way.

[andromaton]

Scroll to the bottom. He always credits multiple people. I assume all of them read his drafts.

[the_common_man]

Next you will say books are out of style

[_x5ft]

How so?

There is a difference between long-form writing and long-winded writing.