My favorite story about docs is when I tried implementing multithreaded Raycast in Unity.

I needed it to hit multiple targets per ray. Should be pretty easy, after all - there is this parameter right in the constructor:

maxHits: The maximum number of Colliders the ray can hit.

And this is how you use it, straight from the docs:

The result for a command at index N in the command buffer will be stored at index N * maxHits in the results buffer.

If maxHits is larger than the actual number of results for the command the result buffer will contain some invalid results which did not hit anything. The first invalid result is identified by the collider being null. The second and later invalid results are not written to by the raycast command so their colliders are not guaranteed to be null. When iterating over the results the loop should stop when the first invalid result is found.

Well, no. It's not working like that. I was always getting just a single hit, but sometimes, I received two or more hits. After a few days of debugging, I have found a typo in bubblesort, which caused the multiple hits, and I was in fact getting only one hit every time.

Strange, must be a bug then. And then I found it. A bug report from 3 years ago. But it was closed as solved. And the resolution?

I have some news about the issue where RaycastCommand will only return a maximum of 1 hit regardless what you set maxHits to.

According to our developers, each individual raycast in a batch only does a Raycast single in PhysX which will only return the first hit, and not multiple hits if the ray passes through several objects which would require a different raycast function. The documentation simply doesn't explain this very well.

The docs above are from 2021. Three years after this. The fuck "doesn't simply explain it very well"? It literally explains it pretty damn well.

But looks like they've finally changed the docs for 2022+ at least, it did happen few years ago.

Because things keep changing and no one ever updates any docs or guides.

Yeah I built a few react apps that made it to production about 7 years ago.

Now the react syntax I used back then is basically a dead language.

This is why having a dedicated person/team to maintain docs is very important

I also feel like agile methodology, which is becoming more common, works against documentation with the fail fast fail often philosophy. If your feedback loop with your stakeholder is rapid, then changes to the design plan are often and rapid as well, which requires more documentation change overhead, which makes documentation even less appealing.

In fact SAFe Agile emphasizes working software over comprehensive documentation.

I know some people don't have the choice but if you do, please choose something better. That garbage does not deserve your effort.

I'm all for progress in technology but sometimes there's a disconnect between planning/budgeting and how it progresses way so fast like when it has a large corporation supporting it's development but folks are writing apps with like two person teams and sustaining these projects for years and need to decide "is today the day I rewrite the whole project to bring it up to date or do I fix that one bug and implement that feature the customer wants?". I swear just keeping code up to date is at least one or two FTEs but it's never included in a budget.

Spring Boot is the worst for this. It seems like every minor update deprecates some security classes which yields a few hours of effort to implement the same damn thing every week

There's a lot of things you can criticize Microsoft for but their documentation is 🧑‍🍳

Because developers have a problem of getting bored with things that already work and want to fix what isn't broken or invent new things.

Where humor

I'm sticking around to see if someone has a good spring tutorial.

Welcome to the churn where everything got replaced every 5 years and old stuff re-appear again as the hot new stuff every 15 years.

Because developers don't bother with documentation. They either assert it's self documenting or they assert whatever it is was always intended to be temporary so it's not worth documenting.

Unreal docs entered the chat

a comment

If you eventually get to the class that can replace it's not that bad. The worst case is when there is no replacement class at all

After 10+ years doing go, js, and ruby, my company is moving me to a Java spring team.

I’ve been looking at baeldung tutorials to get up to speed with spring and reactor and it’s been a pretty good resource.