[aftergibson]

Archive.org shows this went live last September: https://web.archive.org/web/20250108142456/https://learn.mic...

It took ~5 months for anyone to notice and fix something that is obviously wrong at a glance.

How many people saw that page, skimmed it, and thought “good enough”? That feels like a pretty honest reflection of the state of knowledge work right now. Everyone is running at a velocity where quality, craft and care are optional luxuries. Authors don’t have time to write properly, reviewers don’t have time to review properly, and readers don’t have time to read properly.

So we end up shipping documentation that nobody really reads and nobody really owns. The process says “published”, so it’s done.

AI didn’t create this, it just dramatically lowers the cost of producing text and images that look plausible enough to pass a quick skim. If anything it makes the underlying problem worse: more content, less attention, less understanding.

It was already possible to cargo-cult GitFlow by copying the diagram without reading the context. Now we’re cargo-culting diagrams that were generated without understanding in the first place.

If the reality is that we’re too busy to write, review, or read properly, what is the actual function of this documentation beyond being checkbox output?

[raphman]

Huh, I thought that the MS tutorial was older. The blurry screenshot in it is from 2023.

And there ist another website with the same content (including the sloppy diagram). I had assumed that they just plagiarized the MS tutorials. Maybe the vendor who did the MS tutorial just plagiarized (or re-published) this one?:

https://techhub.saworks.io/docs/intermediate-github-tutorial...

[LauraMedia]

You are assuming: A) That everyone who saw this would go as far as post publicly about it (and not just chuckle / send it their peers privately) and B) Any post about this would reach you/HN and not potentially be lost in the sea of new content.

[AlexeyBelov]

They are not assuming everyone would do that.

[anonymous908213]

> readers don’t have time to read properly

> So we end up shipping documentation that nobody really reads

I'd note that the documentation may have been read and noticed as flawed, but some random person noticing that it's flawed is just going to sigh, shake their heads, and move on. I've certainly been frustrated by inadequate documentation before (that describes the majority of all documentation, in my experience), but I don't make a point of raising a fuss about it because I'm busy trying to figure out how to actually accomplish the goal for which I was reading documentation for rather than stopping what I'm doing to make a complaint about how bad the documentation is.

This says nothing to absolve everyone involved in publishing it, of course. The craft of software engineering is indeed in a very sorry state, and this offers just one tiny glimpse into the flimsiness of the house of cards.

[LauraMedia]

I usually would post it in our dev slack chat and rant for a message or two how many hours were lost "reverse-engineering" bad documentation. But I probably wouldn't post about it on here/BlueSky.

[mns]

If you work in a medium to large company, you know most of the documentation is there for compliance reasons or for showing others that you did something at one point. You can probably just put slop at the end of documents, while you still keep headlines relevant and no one will ever read it or notice it.