I had to integrate an internal service. The doc said:

Lorem impsum...

fuck me I had to reverse engineer it.

// ToDo: Done

Worst documentation I've seen?

Our "Coding Standards" 20+ page document. The team who put it together got so detailed, there wasn't much 'wiggle room' for natural deviations in a developer's coding style. For example, a section devoted to no abbreviations. So if you had a variable 'invoiceId', they complained you violated 'standards', even though 'invoiceId' matched a field name in a database table. Using Dapper or another ORM that relied on the 1:1 name match? Nope, you were still forced to inject your own mappers so the code didn't violate standards.

As you can probably guess, such a long, detailed document would have contradictions. I pointed out one of the contradictions. Example:

Page 5: Section B, sub-section B-5, paragraph 3 : "To minimize network traffic, when querying the database, request all the data necessary for the application."
Page 8: Section K, sub-section K-2, paragraph 4 : "For maximum performance, when querying the database, request only the most minimum amount of data necessary for the application ."

In a review I pointed out this contradiction (there were several more)
Me: "If we satisfy A, one could say the code is in violation of B. Which is it?"
<Pointy-Hair-Boss throws his pencil on the table>
PHB: "WHAT IS YOUR PROBLEM WITH STANDARDS! It couldn't be more clear! We are a company of standards because without standards <blah blah..straw man argument..blah blah>"
<deciding not to die on that hill, I move on>
Me: "On page 12, paragraph 9 code is in violation if a method has more than 3 parameters. That seems a little restrictive given our interaction with 3rd party products."
PHB: "There you go again. As stated in the document, ALL code used by the company will comply to our standards. What part of 'ALL' do you not understand?"

Was he bluffing about requiring 3rd party vendors complying with our standards? Heck no. That's a story for another day.

A lot of docker containers.

I often have to use docker containers while I don't understand it as well yet and quite some containers literally come with zero documentation or bad docs.

This both as for how to set the containers up and how to debug stuff.

This is one of the big reasons why I'm not as big of a fan of docker yet.

.net 1.1 had the best documentation ever written. Microsoft spent an enormous amount of money and a dedicated team of skilled engineers just to write them. It was kind of a great time to be a developer, even though the technology is much better now. The current reliance on community docs doesn't hold up as well.

Nobody reads this

This is the story of the API documentation.
Which btw I couldn't find on the producent's website anywhere. I had the pdf shared with me by a coworker.

I knew the api was fucked up the moment I looked at endpoint documentation.

GET params? WHERE, ORDERBY etc. Literally make a SQL select in a GET request.

Returned stuff? The whole thing. Not some DTO, you literally get everything you can get.
Eg if you get IP in your response, you get it in several formats: dotted form, as hex, and as int. In 3 different json fields.

Oh, and regarding IP - one would imagine you can use masks or prefixes for subnets, right? Nope. The only param you can use there is the subnet size. So you have to calculate the power of 2 every time you want to make a request.

That's from the endpoint documentation. But what about some general info on the API, before all that?

As I was looking for something, I decided to read that intro and general info about the API.

Okay, so there was a change log between API versions. "removed [endpoint which sounds like correct REST design], please use [this generic thing with SQL-like GETs]"... Several of them.

And there was also this sentence which said that the API is not restful, "it's REST-like". <facepalm>

If it was a bad attempt at REST API, I would let it go. But this sentence clearly showed they knew they did everything wrong. And the changelog showed they didn't stop there, they were actively making it worse.

What you're about to read is an horror story based on real facts.
Our story begins one week ago, when a dev who calls himself "Arfmann" (what a loser, the f* means arfmann?) decided to take his dev skills to another level.

He always has been scared of databases. He made really bad dream about them. Like, they were screaming at him "SELECT useUs FROM database" while he was crying in some shared preferences noises.

A week ago, he decided to overcome his fear. He learned the basics of SQL. Everything was going well. Until, he decided to implement it on Flutter. A Google's technology.

At first, he decided to appeal to documentation. Went on Flutter web site. Flutter documentation. Sqflite documentation. Started reading. Started doing tests with the code written by Google's engineer.

Everything was fucked up. Dozens of errors, the documentation started to blow up and his PC went on fire, due to Android Studio.

He used a sample project made by Google's engineer. "Maybe if use directly their code it will work. Maybe I was the problem". He wasn't.

The whole documentation was wrong, every single line of code was a spaghetti code (yes, every single line was an entire spaghetti code). Everything was put in the main. If you wanted to try to keep things organized, you would end up punched and beaten up from the code itself. It would become a sentient entity that will beat you the fuck up.

Really scary.

SAP shit. Bad documentation by design.

From what I’ve seen and experience while messing around with other languages, PHP and Rust have some of the best while C# has the worst.

Worst documentation? Unreal Engine 4's documentation on editor customization (custom panels/windows and whatnot). It might have improved in the last two years, but the last time I made a custom editor there was almost zero documentation on the matter and on their Slate UI framework. The little documentation that existed was very vague and had awful examples.

I don't remember very well, but I think it took me close to two weeks to get something very basic working. I had to read a LOT of C++ code filled with generics and macros to figure everything out, but after I did I enjoyed a lot working with that stuff.

I just don't know how I was able to do that, working with UE4 was a pain the butt every. single. day. Runtime error on the gameplay code? Too bad, the whole editor will crash and then take ~40s to reopen. It was crash after crash, ~1min of compilation time for any little change to the code, so so so so much frustration.

I do miss a those times a bit though, because even though it was hard, it felt good to feel competent, to know something complex reasonably well to the point I could help people on forums. Today I always feel I don't know enough about the languages/frameworks I use. It's kinda depressing, it takes a huge toll on my self confidence. But whatever, let's keep going, one day I'll get there :)

//TODO: Make this code great again so Donald would be proud

Best? Clojure docs. They have disqus-like thing under every function description where anyone can submit their usage example. One example times forty submissions equals forty examples!

Also w3c specs, nuff said.

Worst? GunJS. Multiple websites that look like each other plus GitHub wiki all with the same content but idk which one should I use, also there is no complete source, you have to look up everywhere. Also NextJS, they’re too busy pitching to investors, there is no way of contacting them, you’re in your own if you choose nextjs, that’s why I banned it everywhere I have the power to ban things

Best documentation, cakephp/laravel

Worst is by far Java docs...
for fucks sake include some useful examples i dont wanna see a table with parameters, My IDE can provide more helpful info than that

Best documentation?

Ucglib, a universal TrueColor library for many display controllers for Arduino. Seriously, this thing’s documentation is fucking SICK. They include so many fonts on there, every single one is customizable and every customization is documented.

Worst documentation?

Probably the Objective-C syntax documentation, it’s DIABOLICAL, you have to, first of all, FIND IT. After that, you need to understand the shitty language.

Best : Open source projects.
Worst : Legacy proprietary systems. Most of them you can only wish you have documentation and lucky if you are able to run those systems on your computer.

Not the worst, but deserves a mention due to how common it is.

Say your whatever object has a method called Configure. You can infer a lot from the configuration parameters or type that it takes, but for whatever reason something is unclear or doesn't work.

Tooltip from xml comments: Sets the configuration.
Official guide: Sets the configuration <br />.
Technical API reference: Sets the configuration.

I would create a support ticket explaining how this is unclear if I wasn't half expecting the suggested solution to be "you know what I mean".

Best: Public docs, especially quick start guides... That actually work.

Worst: my team's. It's basically non-existent... I'm the only one that writes docs and design diagrams and well that's mostly for myself to remember/understand stuff and use when ppl ask....

My first response is usually like: "Here RTFM... (Now go away because I have other things to do)"

Worst documentation I've seen?

Any+All documentation auto-generator using the (XML) code comments (GhostDoc, etc).

Worthless, utterly and completely worthless. Worse than having no documentation.

Pathoschild's Stardew Valley ModAPI.

"The documentation were you are the hero."

Documentation made for installing a crappy app. Seems well presented but all steps are in a random order.

I had a colleague who was telling me "okay you must do page 54 before page 15, then page 30..."

Worst doc ever :)

Unreal Engine 4 has the worst for sure. And i mean official docs as well as forums.

Answers to most questions tend to kind of boil down to "it's easy!".

As in, that's the only thing the answer will tell you. that it's easy to do. And by that implication, they don't actually need to tell you how to do it.

Or something like "it's easy, just turn this setting on/off".

Nobody will tell you, though, which tab in what window opened by which tiny button in a property grid in a window opened by which dropdown submenu under which button in what toolwindow to find that option.

Second place in the list of worst is shaders: ShaderLab/HLSL. Because they at least don't pretend that it's easy and that they're giving you answers, they usually just don't exist.

Best? Anything half-decent is the best thing ever since it exists and is okay. Worst? "//TODO" or fucking nothing entirely. (Alternatively: paid-only "please buy this hardcover book" docs!)

Docker and Docker Compose. They're both.

All of them.
.
.
.
.
.
.

At the time I were a newbie all the documentation's seemt crap.

Not the worst documentation but the fact that I even have to google the simplest things every single time for the simplest problem. It’s time consuming, I get distracted and I feel dumb for not knowing how to read a Json :)

Best documentation have probably been most language docs and references I've worked with, official or otherwise, especially C++. Completeness, consistency, tidiness and examples really help a lot, since I know I can rely on the docs for basically any problem and makes work so much easier since I'll be guaranteed to leave understanding what's up.

Worst documentation has got to be the internal docs we had to create for a seven-man uni project, you couldn't find shit in the sea of docs that were out of date or just plain wrong. It was so much easier to ask whoever was working on that part about the intricacies of the cobbled-together mess than to either read the code or the docs. One absolute mouthbreather was working on the database docs and put in that it stored ArrayLists. Fucking Java ArrayLists in a motherfucking database. One day I am going to rant so hard about this dumbass and it's gonna be a spectacle.

Bonus points goes to the company's public documentation at my internship. It was good and pretty complete, but sometimes there was a document from 2 years ago that had been written by a non-english speaker that was absolutely awful. Some of them were so bad that as soon as I'd finished learning what I needed to, my mentor told me to go and fix the docs, I don't blame him.

Best: the U2 pilot's handbook, as you _wanted_ to read it.
The S370 assembler docs. Everything you needed and nothing more.

Worst: where to start? How about the defect reports produced by contemporary QAs? Maybe a screenshot, and an implied demand for telepathy. Mate, you're a mindless drone, the definition of brainless. Applying telepathy on you is pointless.

Python(and most modules and frameworks) and C++ for the best documentation for sure

I love the ansible documentation, so many examples which cover so many use cases and all the descriptions of all the possible arguments are very clear :)