undefined | Better HN

0 pointsgrrdotcloud2y ago0 comments

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.

0 comments

GavinMcG2y ago

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.

projektfu2y ago

It's lousy documentation but it makes great coffee.

grrdotcloudOP2y ago

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

echelon2y ago

> pored over

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

vsareto2y ago

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.

KnobbleMcKnees2y ago

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-iq2y ago

Django docs come to mind

KnobbleMcKnees2y ago

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.

j / k navigate · click thread line to collapse

0 pointsgrrdotcloud2y ago0 comments

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.

0 comments

GavinMcG2y ago

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.

projektfu2y ago

It's lousy documentation but it makes great coffee.

grrdotcloudOP2y ago

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

echelon2y ago

> pored over

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

vsareto2y ago

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

KnobbleMcKnees2y ago

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: