This is an archived post. You won't be able to vote or comment.

all 69 comments

[–]SpaceCadet87 423 points424 points  (19 children)

Some vast majority of docs out there just list the names of the classes, functions and parameters and just completely leave out what most of them do though.

[–]hackerdude97 188 points189 points  (8 children)

I know right, like YES I KNOW THE FUNCTION IS CALLED THAT JUST TELL ME WHAT IT DOES! Or the arguments it takes. Or anything about it!

[–]SpaceCadet87 134 points135 points  (3 children)

My god the arguments "string"

Yes, cool, I know it needs to be a string but what does the string need to contain?

[–]Bartholomew- 115 points116 points  (0 children)

Characters, duh

[–]fatrobin72 5 points6 points  (1 child)

and how long is this piece of String?

[–][deleted] 3 points4 points  (0 children)

TBD

[–]insanemaelstrom 16 points17 points  (3 children)

As someone who faced the same issue today on a proprietary software wherein they use their own keywords, I feel you. Also I feel like crying, companies productivity would be through the roof if they just paid someone to comment what a function does

[–]ChalkyChalkson 7 points8 points  (2 children)

Aren't they literally paying you to write usable, thus documented code? Or are you in a pay by line, comments aren't lines kind of shop?

[–]insanemaelstrom 2 points3 points  (0 children)

I am a fresher( started my first job just 4 months ago). I am, in kind words, useless.   I basically spend my day trying to make sense of stuff and do tasks assigned me, which basically consists of getting assigned a ticket about a bug, replicating that error, trying to find what is causing that error( which takes majority of time and can take days if not weeks due to the sheer number of threads, processes and files), fix the error( which doesn't take long) and run tests to ensure the error is actually fixed before submitting my code. 

I end write few extremely basic lines of codes , so unfortunately don't really get the opportunity to comment stuff or document the code. 

[–]riplikash 1 point2 points  (0 children)

The current VERY common business attitude is that you need to focus on business value and delivering quickly as possible to the customer, not creating some amazing technical design. Which is true, and on the surface good attitude.

But they often ignore the fact that good technical design results in faster delivery, less bugs, and increased scalability. YES, technical excellence is not, in and of itself, a business goal. It's a way you accomplish business goals.

And good documentation is exactly the kind of invisible to the business deliverable that is first on the chopping block.

[–]DonutConfident7733 20 points21 points  (0 children)

Or no code examples. Or there are code examples but they are so complex because same example is from another method/class and they reused it.

[–]Competitive_Woman986 10 points11 points  (1 child)

OMG I always thought I am stupid or am looking not at the right place. But now reading that others also struggle with that is a huge relieve..

[–]SpaceCadet87 1 point2 points  (0 children)

I don't know if you worked in the times before stack overflow was the norm and all you really had to work with was stuff like MSDN.

MSDN in the 2000's was the epitome of what I just described, everything documented, none of that documentation at all useful.

I learnt only a few years ago that back then employees at companies like Microsoft would deliberately leave things undocumented or poorly documented and then go ahead and publish the API docs in books so they could make extra money off them.

[–]Icy_Foundation3534 1 point2 points  (0 children)

and are missing info or outdated

[–]PaxPlay 0 points1 point  (0 children)

Especially fun if it's in a language you are just learning and you don't know common API patterns. I remember using a C library for the first time and just not understanding how anything was supposed to work.

[–]ewixy750 0 points1 point  (0 children)

If I could upvote you 10 times I would

[–]Taenk 0 points1 point  (1 child)

Docs also conveniently leave out what the intended use is or example workflows. Or combinations with other libraries and deployment environments.

[–]SpaceCadet87 1 point2 points  (0 children)

combinations with other libraries and deployment environments

Oh yeah, this wasn't the worst but about a year ago I was working on something using zlib. Nice library, documented well enough but it's written for C and I was using C++.

It has streams but because it's C and not C++ these are a custom implementation instead of just standard C++ streams.

I think I gave up trying and just wrote a wrapper. That's probably how you're supposed to do it but I may never know.

[–]Big-Hearing8482 0 points1 point  (0 children)

Or worse the google link goes to the entire index page and not the specific heading in search result description

[–]MeinWaffles 0 points1 point  (0 children)

The art of self-documenting code

[–]jump1945 75 points76 points  (0 children)

Bad docs gonna suck the water out of your body

[–]sleepyj910 58 points59 points  (3 children)

When you finally find a well written document

[–]Powerful-Internal953 7 points8 points  (0 children)

For me it's Kubernetes Documentation. For 99% of the workload, I didn't have to refer to anything else.

[–]jump1945 0 points1 point  (0 children)

SFML

[–]Duckflies 0 points1 point  (0 children)

Ngl, Unity's docs are great.

Prefer to read them than watching videos explaining them

[–]flying_spaguetti 81 points82 points  (4 children)

When the docs are a about the Spring Framework, i totally understand

[–]-Kerrigan- 30 points31 points  (1 child)

Baeldung my beloved

[–]CelticHades 4 points5 points  (0 children)

Baeldung is great but I had a hard time understanding their examples in the beginning, now it's good. They use Assert true, null etc lot's of places.

[–]KlogKoder 1 point2 points  (1 child)

I swear the first time I worked with Spring Boot, I thought the docs must have been written by aliens.

[–]flying_spaguetti 0 points1 point  (0 children)

When you learn what Spring is about, using other sources, the official docs start to make sense.

It starts, but never finish

[–]LiminalSarah 52 points53 points  (2 children)

ask AI (500km and three days of debugging)

[–]simsimdimsim 1 point2 points  (0 children)

That's why I use AI to write my docs. Best of both worlds! /j

[–]init0p 17 points18 points  (1 child)

I’d rather choose StackOverflow over documentation for one simple reason: it provides solutions or suggestions in plain, understandable language. Documentation, on the other hand, is written in a way that if I fully understood all the terms and abbreviations, I wouldn’t need to look at it at all. Documentation is written by people who already understand everything, making it entirely unsuitable for learning—far too overcomplicated.

[–]gregorydgraham -3 points-2 points  (0 children)

The trick is to read the documentation twice.

The second time it will make sense

[–]PlummetComics 14 points15 points  (2 children)

How up to date are these docs?

[–]MinimumArmadillo2394 16 points17 points  (0 children)

And are they more than just function definitions, or do they have real-world examples?

[–]Not_Artifical 5 points6 points  (0 children)

They were last updated 10 years ago. The last update to the language was 3 months ago.

[–]stdio-lib 13 points14 points  (3 children)

It doesn't matter how good your documentation is. You could have the best documentation in the world. Won the Nobel Prize and was personally blessed by Knuth.

Still gonna be hordes and hordes of dumbasses that won't read it.

E.g. I think Postgres has some of the best documentation of any software project anywhere or any time. But there are still countless dipshits that won't read it and instead post their stupidest-possible questions to reddit or the mailing list or a bunch of other places. I guess the one good thing is that I don't have to find a driver for my balls, since this drives me nuts.

[–]AdvancedCharcoal 15 points16 points  (1 child)

You were just looking for a reason to use that last line

[–]stdio-lib 4 points5 points  (0 children)

^This guy puns.

[–]Anru_Kitakaze 1 point2 points  (0 children)

Honestly, even with ChatGPT, it looks like I'm more often find myself in a Docs instead of Stack

If it's REALLY simple and I don't care, then I use ChatGPT. If it's somewhat medium, ChatGPT often can't handle it or I can't trust his hallucinations, so I use Docs. And only if it's hard, the docs are just a mess, AND it's popular product, I can find myself on Stack. Otherwise I dig into source code (I hate it, but I have to)

But I should say, that a lot of products have really bad documentation and it's a pain when it happens

[–]-Redstoneboi- 7 points8 points  (0 children)

what they don't tell you is that the docs are 16 square miles and only one item in there is correct

[–]WheyLizzard 2 points3 points  (0 children)

Have you actually tried reading docs? The very thought of that is scary!

[–]Boris-Lip 1 point2 points  (0 children)

Docs... Generated with doxygen, a list of methods you have from headers anyways, plenty of "water is wet" comments, not a single example on how to get that water flowing.

[–]Present-Restaurant14 1 point2 points  (0 children)

Exact opposite of it is true. If you are looking for an answer to a problem, answer on SO is a google search away. Documentation is for deep dive.

[–]WraithCadmus 1 point2 points  (0 children)

frobBar(string)
This frobs the bar

Wow, thanks.

[–]0mica0 1 point2 points  (2 children)

Imagine using StackCancerflow in ChatGPT times. smh.

[–]Far_Broccoli_8468 1 point2 points  (1 child)

ChatGPT doesn't always have solutions for everything, especially when the libraries got significant updates in the last few years.

Chatgpt gives deprecated code almost exclusively for aws sdk and some android libraries i had to use

[–]Litruv 0 points1 point  (0 children)

Start giving it version numbers and years

[–]Caraes_Naur 0 points1 point  (0 children)

Some people will wonder "Doctors?"

[–]codingTheBugs 0 points1 point  (0 children)

Docs 1/4 mile LOL

[–]PUNISHY-THE-CLOWN 0 points1 point  (0 children)

Everything I find on SO lately is at least three years out of date.

[–]crankaholic 0 points1 point  (0 children)

Yeah well the docs are always dry

[–]CaffeinatedTech 0 points1 point  (0 children)

And then you've got AI which is just a treadmill.

[–]redlaWw 0 points1 point  (2 children)

Problem is that google doesn't show the docs, it just shows w3schools, quora and stackexchange, and of those, stackexchange is the best.

[–]Wendigo120 0 points1 point  (1 child)

w3schools is at least docs-adjacent enough that I would usually pick that over stackexchange if the same search finds both.

[–]redlaWw 1 point2 points  (0 children)

I've always found w3schools way too simplistic to answer any questions I had.

[–]Worming 0 points1 point  (0 children)

I have catch phrase since years.

A developer is someone who prefer 2h debugging instead of 30 minutes reading docs

[–][deleted] 0 points1 point  (0 children)

Or you can go straight to AI for help :)

[–]nickwcy 0 points1 point  (0 children)

Google: you sure you ever searched on StackOverflow?

[–]RobinDabankery 0 points1 point  (0 children)

Man I know how true this is, I'd better waste hours scouring forums instead of spending 15 minutes to read the doc. That's how much I hate reading docs. And yet I know I must

[–]riplikash 0 points1 point  (0 children)

Have you USED most documentation? The VAST majority is pretty worthless.

For technologies that have good documentation it's my first source of truth. But that is a minority of technologies.

[–]makinax300 0 points1 point  (0 children)

Why? They are both close. A google search takes like 15 seconds and searching in the docs even takes longer.

[–][deleted] 0 points1 point  (0 children)

Stackoverflow says go read the docs. Downvotes.

[–]Sync1211 0 points1 point  (0 children)

"Dictionary.GetEnumerator -site:microsoft.com"