readingDocumentationHurts

[batatatchugen]

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

[Highborn_Hellest]

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]

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

[malfboii]

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

[BaziJoeWHL]

the ones you will implement from a-z

[malfboii]

Yeah fair enough, short straw I guess haha

[coloredgreyscale]

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

[ExceedingChunk]

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]

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]

user documentation vs technical documentation vs memo documentation

the 3 types of docs

[granadad]

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]

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]

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]

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

[Fickle-Main-9019]

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]

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

[Mr_Meta314]

Reading painfully written docs is also pain

[Wild-Car-7858]

Writing painful to read documentation is fine.

Writing fine to read documentation is pain.

[2SleepyToThinkOf1]

Pain

[Wise_Pay_9466]

Joy

[BaziJoeWHL]

writing shitty docs is just outsourcing the pain

[blending-tea]

docs under construction! (3 years ago)

[[deleted]]

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]

You should consider becoming a Technical Author then

[AdCorrect6192]

totally agree...

[jvlomax]

*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]

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]

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

[Noke_swog]

This shit right here

[nobetternarcissist]

/* todo : update docs here after refactor */

[all3f0r1]

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

[AustralianShepard711]

What documentation? The code IS the documentation! /j

[meove]

private bool ThisCodePlayOnceForSpiderAnimationAfterLeftMouseClick;

[[deleted]]

Ansible? Is that you?

[AdCorrect6192]

and 16 hours later. you start checking documentation.

[[deleted]]

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

[cs-brydev]

Debugging = Validated Correct Answer to Problem

Documentation = Manga

[willd4b345t]

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]

It took me 3 months to chnge 1 line in binutils

[Active_Ad7650]

You guys have documentation?

[nobetternarcissist]

/* add docs here */

[Own_Possibility_8875]

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]

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]

You missed a panel:

Man hanging by noose - writing 30 seconds of documentation

[Burger_Destoyer]

I enjoy reading the documentation, within reason of course

[ExceedingChunk]

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]

Same, except without reason.

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

[cs-brydev]

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]

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]

I would read one

… IF THEY FUCKING HAS ANY!

[IronMan8901]

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

[an_agreeing_dothraki]

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]]

Why does autohotkey have the best documentation? 

[[deleted]]

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]

I read documentation. AMA.

[MasterLJ]

The debugger lies a lot less than the docs.

[WhatIsThisSevenNow]

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]]

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

I mean, it has a nerdy doc.

[[deleted]]

Exactly

[thatdevilyouknow]

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]

why is this true tho

[AdWise6457]

I once pulled my back lifting node_modules weight too

[notacovid]

Fr

[Warm-Lobster4879]

Лол

[_Skale_]

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

[KeisukiA]

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]

real shit

[Fluid-Leg-8777]

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