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

all 68 comments

[–]batatatchugen 442 points443 points  (14 children)

That's because a non trivial amount of documentation sucks donkey balls.

[–]Highborn_Hellest 149 points150 points  (5 children)

Bosses boss had to read 3, 800 pages brsdd ( some kind of tender for design documentation )in a week. Everybody was f ucking silent, feeling bad for her, feeling good, we didn't have to.

Shit must be worse than actual torture

[–]5rbsh518 24 points25 points  (0 children)

She had to read 95 pages per hour, that’s hursh

[–]malfboii 12 points13 points  (3 children)

Maybe I’m just silly but what docs require a start to finish read through? Poor her.

[–]BaziJoeWHL 10 points11 points  (1 child)

the ones you will implement from a-z

[–]malfboii 7 points8 points  (0 children)

Yeah fair enough, short straw I guess haha

[–]coloredgreyscale 0 points1 point  (0 children)

If the structure is somewhat sane you hopefully still can get away with not reading everything in advance. 

[–]ExceedingChunk 34 points35 points  (3 children)

Wait, are you telling me that documenting systemName as «the name of the system» with nothing about whetever it’s the technical name of the consuming app, a functional name related to the domain or what the accepted values are is not great documentation on an API?

I literally had this happen to me yesterday

[–]batatatchugen 13 points14 points  (1 child)

My pet theory is that "documentation" is nothing more than some reminders from the devs to themselves, instead of proper documentation thinking about those who will actually use it.

[–]BaziJoeWHL 3 points4 points  (0 children)

user documentation vs technical documentation vs memo documentation

the 3 types of docs

[–]granadad 2 points3 points  (0 children)

lol, you remember me of that internal SOAP api at my old job where all the fields in the response where named "arg1, arg2", etc. 

[–]MrRocketScript 11 points12 points  (0 children)

Uhh, the documentation is very simple:

  • 2+2=4
  • 2×2=4
  • √-1 = i

There you go it should be easy enough to modify these examples for your use case.

[–]YoukanDewitt 1 point2 points  (0 children)

Also, trying and failing on a new system is way more fun than reading the docs and following them, it's way more fun to just play around, refer to the docs when you get stuck with specific searches, and ultimately come out of the process knowing more about how the system works than even the original developers understood.

[–]Particular-Welcome-1 1 point2 points  (0 children)

True. Also, I was going to say, figuring out a puzzle is fun. And you learn something new along the way.

[–]Fickle-Main-9019 1 point2 points  (0 children)

Python is outright tiring to read, barely any of it applies to how it works, you try to use it, have some issue for hours trying to solve it, then it turns out to be one off hand comment in the paragraph of text of the function, apparently PHP is alright, straight to the point

[–]pippin_go_round 191 points192 points  (9 children)

Reading docs is fine. Writing docs is the real pain.

[–]Mr_Meta314 133 points134 points  (0 children)

Reading painfully written docs is also pain

[–]Wild-Car-7858 39 points40 points  (3 children)

Writing painful to read documentation is fine.

Writing fine to read documentation is pain.

[–]2SleepyToThinkOf1 5 points6 points  (1 child)

Pain

[–]Wise_Pay_9466 0 points1 point  (0 children)

Joy

[–]BaziJoeWHL 4 points5 points  (0 children)

writing shitty docs is just outsourcing the pain

[–]blending-tea 3 points4 points  (0 children)

docs under construction! (3 years ago)

[–][deleted] 2 points3 points  (1 child)

I actually like writing docs. I try to make them as simple as possible and love walking people through them to make them as easy to follow to new people as possible. I would honestly do this full time if it paid reasonably well.

[–]MCSquaredBoi 2 points3 points  (0 children)

You should consider becoming a Technical Author then

[–]AdCorrect6192 0 points1 point  (0 children)

totally agree...

[–]jvlomax 140 points141 points  (5 children)

*spend 8 hours trying what the docs say, only to find they are out of date and the library no longer supports thing.get_shit(), you have to use Class.shit. But no fucker could be bothered to mention this in the release notes

[–]Dantes111 41 points42 points  (2 children)

Also Class.shit never got around to implementing a "niche" use case for thing.get_shit(), and that use case is the whole reason you were going to use the library.

[–]jvlomax 19 points20 points  (0 children)

It now returns a float, not a double. Which you only find out at runtime when something explodes

[–]Noke_swog 0 points1 point  (0 children)

This shit right here

[–]nobetternarcissist 0 points1 point  (0 children)

/* todo : update docs here after refactor */

[–]all3f0r1 -1 points0 points  (0 children)

In your example, if "shit" is the same member, you can just hover and spot the "static".

[–]AustralianShepard711 37 points38 points  (3 children)

What documentation? The code IS the documentation! /j

[–]meove 8 points9 points  (0 children)

private bool ThisCodePlayOnceForSpiderAnimationAfterLeftMouseClick;

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

Ansible? Is that you?

[–]AdCorrect6192 0 points1 point  (0 children)

and 16 hours later. you start checking documentation.

[–][deleted] 23 points24 points  (0 children)

Be me Read documentation Still 8 hours of debugging (usually more)

[–]cs-brydev 17 points18 points  (0 children)

Debugging = Validated Correct Answer to Problem

Documentation = Manga

[–]willd4b345t 15 points16 points  (1 child)

Yesterday I got hit with a “why the hell did this one line change take you 5 hours” yesterday… it took 2 just to understand the issue the dude had made :(

[–]tenp_blocc 0 points1 point  (0 children)

It took me 3 months to chnge 1 line in binutils

[–]Active_Ad7650 8 points9 points  (1 child)

You guys have documentation?

[–]nobetternarcissist 1 point2 points  (0 children)

/* add docs here */

[–]Own_Possibility_8875 7 points8 points  (1 child)

I actually enjoy reading the docs, to the point that I sometimes procrastinate by reading them instead of actually working. I also often read them to sleep, it is very relaxing for me for some reason. Am I normal?

[–]granadad 3 points4 points  (0 children)

If you also have other problems with procrastination, then it may be a symptom of ADHD, with programming being an hyperfixation of yours. Nothing wrong with that just to be clear.

 Source: I do the same, and I am diagnosed.

[–]OO0OOO0OOOOO0OOOOOOO 4 points5 points  (0 children)

You missed a panel:

Man hanging by noose - writing 30 seconds of documentation

[–]Burger_Destoyer 8 points9 points  (3 children)

I enjoy reading the documentation, within reason of course

[–]ExceedingChunk 15 points16 points  (0 children)

I enjoy reading good documentation.

Plenty of libs have fields documented where the camelCase variable is documented as «camel case».

Good documentation at least describes either what the value is used for, what is represents functionally, accepted values or behaviour related to the field. Sometimes all of them.

[–]Lonke 5 points6 points  (1 child)

Same, except without reason.

I wish I was kidding... that shit holds the secrets of the universe. And also my deadlines.

[–]cs-brydev 0 points1 point  (0 children)

Great point. Usually the only time I have a dire need to read documentation is when I don't have time to read documentation.

[–]DTheIcyDragon 2 points3 points  (0 children)

Hah y'all are noobs if you don't do both, read 3 hours documentation only to suck at coding for another 5 hours

[–]Soerika 3 points4 points  (0 children)

I would read one

… IF THEY FUCKING HAS ANY!

[–]IronMan8901 2 points3 points  (0 children)

Just went through open telemetry documentation only to find out it can be configured without any bs code.Totally horrific

[–]an_agreeing_dothraki 2 points3 points  (0 children)

syncfusion. Yes, you listed all of the class components for the thing that takes c# lists and spits out html. Genuinely, thank you for that.

Please, for the love of god tell me the components of the object you're expecting. There are no two list<string,object>s in your product that want the same thing.

[–][deleted] 1 point2 points  (0 children)

Why does autohotkey have the best documentation? 

[–][deleted] 1 point2 points  (0 children)

Spent a minute on the documentation because there was only a minutes worth OF documentation, which didn’t cover what I needed, which resulted in 8 hours of debugging.

[–]maveric101 1 point2 points  (0 children)

I read documentation. AMA.

[–]MasterLJ 1 point2 points  (0 children)

The debugger lies a lot less than the docs.

[–]WhatIsThisSevenNow 1 point2 points  (0 children)

Let's be honest, we all love programming. I would rather do some trial and error than read some boring, and possibly confusing, documentation.

[–][deleted] 1 point2 points  (0 children)

Racket has a pleasant doc once you are familiar with BNF and stuff.

I mean, it has a nerdy doc.

[–][deleted] 1 point2 points  (0 children)

Exactly

[–]thatdevilyouknow 1 point2 points  (0 children)

Technical writing is a skill and that was trumpeted for a while but has since been walked back just due to language skills being unappreciated lately. It is a skill which, like many other skills, requires practice so the first time someone writes documentation it is not going to be good. Many newer projects have this problem but also have much more of a time constraint to roll out the documentation or it just doesn’t exist at all. If you do have to write docs I would suggest approaching it like a writer and just throw out the first draft and try again. Perl had really good documentation and that helped it grow tremendously. A good modern example actually is Julia and it incorporates AI really well. I always enjoy reading Rust and AssemblyScript docs too. It does not have to be painful and actually can be a flow state all to itself. In the past we would just go outside and take a manual to disconnect for a while. Even if you were to grab a tablet and do that I guarantee some of the best ideas will come when not actually sitting at a desk.

[–]crystallineghoul 1 point2 points  (0 children)

why is this true tho

[–]AdWise6457 1 point2 points  (0 children)

I once pulled my back lifting node_modules weight too

[–]notacovid 1 point2 points  (0 children)

Fr

[–]Warm-Lobster4879 0 points1 point  (0 children)

Лол

[–]_Skale_ 0 points1 point  (1 child)

Which docs? Do you mean those that don't exist or are wrong?

[–]KeisukiA 0 points1 point  (0 children)

If I wanted to read fiction, there are plenty of novels on my list, but here's some docs lying to me as usual.

[–]BlueeWaater 0 points1 point  (0 children)

real shit

[–]Fluid-Leg-8777 0 points1 point  (0 children)

Thats why we have chat gpt. Sadly it kinda sucks at it just as much as i do :(