Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple APILearn More
Search - "wk225"
I had to integrate an internal service. The doc said:
fuck me I had to reverse engineer it.5
Best: Requirements written by the CTO in my previous company.
Worse: Requirements written by the BA in my previous company.
Worst: Any type of documentation written by the guys who kept putting their fucking names in the source code and bragging about how robust and how much time they spent updating an API in the description of the endpoint itself. All of this nonsense and they don't write the actual information you need. When they do, it's fucking wrong. The spellings are wrong, the data types are wrong, and the steps in README are wrong.4
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.12
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.9
.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.2
Python's is unbelievably good. I guess I took it for granted because in many other languages it's impossible to find the official documentation, or if you do it's too formal because the language is a "standard" not a fucking ACTUAL LANGUAGE. When I tried to learn Ruby, what mostly stopped me was being unable to find what I was looking for.
I think it's an SEO thing because once I've found it, it generally answers my question. The top result is always from some bullshit blog or tutorial site, whereas in Python the right thing is always front and center.4
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.1
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 :)
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.8
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
LXC, no doubt.
I mean to be fair, LXC is an amazing container runtime once you manage to set it up. But setting it up is the hard bit. Starting off with LXC 2.x, it was a nightmare to find out how to get things like the storage backends working. But with ZFS it ended up being alright. Find some arcane values to stick in the /etc/lxc/default.conf to use ZFS as the backend and then the default storage location on those ZFS pools (I'll get back to that later), and it worked alright. Again, once it works it's great, but setting it up and finding the right configuration keys is absolute hell.
So, LXC 2.x for a while and a few months ago I finally ended up upgrading to 3.x. Every single configuration key changed. Every single one of them, and that's why I had to 1) learn LXC all over again, and 2) redeploy each and every one of my containers. That process is still not entirely completed. ZFS backend was once again a dive into arcane configuration keys found on forums and whatnot. Yeah.. official documentation has none of it. Oh and in 3.x you now also have to dodge the torrent of "just use LXD m8" messages. Yeah, very helpful when LXD is also the ONLY way to reasonably configure it. Absolutely beautiful. Oh and as far as the ZFS default storage location goes (such as ssd/lxc/ct)? Yeah forget about it. There's no configuration option for it anymore, and the default is "lxc". In ZFS lingo that means that LXC has the audacity to demand a whole pool for itself. No. No you don't deserve a whole pool for yourself. But hey at least you can define the storage location to use in the lxc-create command! Every single time you have to define it in lxc-create. I abstracted it away into my own LXC interface, so no big deal really. But yeah... That could absolutely be better. And in 2.x it was actually better.
Oh and btrfs, the filesystem I'd like to use on low memory systems because ZFS' ARC is too much on such systems? Yeah forget about it. I still have no idea how to do it. Thank you LXC and its amazing documentation!
And if you want the icing on the cake for LXC's terrible documentation, see their repo's index page at https://github.com/lxc/lxc/.... Yeah, it's totally still at 2.x... That's how well they maintain that. Even Debian has 3.x now. And if you look at the branches, you'll find that even 4.x is already available and considered stable.
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.
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 that4
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)"
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".2
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.
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.
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.1
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.1
Best: The Ada 83 Language Reference Manual.
Ada was picked as the teaching language for a while when I was an undergraduate. All the supplied information about the language was at best vague, at worst wildly misleading. But then I came across the LRM in the library, and it had all the answers. All Of Them.
Close runner up: The Annotated C++ Reference Manual.
Back before C++ became too large for any one mortal mind, this reference both contained the 'ground truth' standard _and explanations of what lead to the choices made in that standard_. Just an excellent reference.
Worst: CMake documentation.
The man page was unnavigable, until they tossed it and you had to use the webpage or the idiosyncratically organized help output from the program.
CMake is stupidly complicated already, with bizarre parsing, thousands of odd special case behaviours, and weird interactions between various features and tools. Good documentation might have made that manageable, but no: answering any question requires a measure of clairvoyance, which will inform you that the thing that you need is in fact described off hand halfway down the 4 pages of rambling text in a completely different part of the docs. And then they changed it 2 versions ago.2
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.
"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 :)2
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!)2
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 :)4
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.
Best documentation seen included all required steps for installation and config files with comments explaining each config line.
Worst documentation was a non-existant one for bunch of stuff that is critical for operation. Some ppl knowing some minor parts of solutions used not knowing what is legacy and what not.
Worst documentation: macOS developer API, e.g. the already deprecated kauth API still have documentation like this: https://developer.apple.com/documen...
Really good on the other hand, this: Ordered the stuff, waited 3 months, flashed the NodeMCU and assembled it within 10 minutes:
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 :)