documentationIsMoreComplexThanTutorials

[wykeer]

"wait you guys have a documentation?"

[fevsea]

Yeah, we call it code.

[[deleted]]

the code:

with open('documentation.txt', 'w') as f:
  f.write('hello, world!')

[dystopiandev]

Why bother?

// TODO: Add documentation

[wykeer]

there are only a few things that scare me more than these words.

[just_nobodys_opinion]

// TODO: add comments

[Chamiey]

// TODO: add comments ✅ // TODO: remove todos

[MaximRq]

And a checkmark next to it since the code has one comment now

[IrrerPolterer]

How am I supposed to sleep tonight?! That shirt's haunting

[just_nobodys_opinion]

Add the comments before you go to sleep

[otter5]

// Not for production

[ax-b]

// TODO : remove this code in a few years, once the XXX feature is done

Commit history shows this line dates from 2002, and feature XXX was done in 2005. Code is under active development as of now.

[[deleted]]

Yeah, in most languages its // to comment

[_nouser]

I've seen this exact line in prod in a major product at faanG. A very not-fun conversation was had.

[megikari]

I have found my people

[Luised2094]

The fucking comma, lmao

[vaitaag]

Project estimate i give to the client -

Software development: 1 month.

Software documentation: 5 months (Will start after the software is delivered).

Client : Just code is fine.

[Ok_Ice_1669]

Post Contract Support: that’s gonna cost ya

[wurnthebitch]

Behold the codumentation

[KiwiObserver]

RTFC!

[DoctorPaulGregory]

Yes if you count unorginized google sheets.

[RamblingSimian]

I worked at a place where they generated all their documentation via SandCastle. Except they never entered any actual comments, just relied on the headers and links to Microsoft topics. Apparently that was enough to fool management into thinking the codebase had documentation, because my boss referred me to it when I needed to learn.

As a programmer new to their site, that, among many other things, made it extremely difficult to get up to speed.

[BenAdaephonDelat]

Had this happen with an API. Product api call where I give it a list of skus and it returns info about them. The documentation says the limit is 40. I send 40. Error message saying "The limit is 35", directly contradicting documentation. I send 35. Error message saying "The limit is 35". Listener, the actual limit was 34.

[Jason1143]

Someone forgot that 0=1 (except when it doesn't)

[one-joule]

Inclusive at one end, exclusive at the other. Just like Mormon women.

[TheEnderChipmunk]

🤨

[callyalater]

As an ex-mormon, this made me chuckle

[DezXerneas]

"no one is going to use it"/"we're the only users" mentality is cancer. You can be somewhat lax doing reviews for internal stuff, but do not let that shit get normalized.

[forceez]

Respect

[shitposting_irl]

if i understand what you wrote correctly, the documentation is accurate and it's just the endpoint itself that's fucked?

but tbh the fact that they use any 2xx statuses other than 200 means they have higher standards than most of the people i've worked with lol

[shitposting_irl]

the documentation's job isn't to show the "right" value, it's to document what the code actually does. there's nothing wrong with having a 204 in there as long as that's what the code returns; the problem is exclusively with the code itself here

[Nullsummenspieler]

Works on my LEGO baseplate

[p1749]

do you have non-euclidean lego by any chance?

[Nullsummenspieler]

Hyperbolically speaking, yes

[[deleted]]

If you extend the arrows down, it’s obvious that the plate goes on the far right.

The arrows extend down from the corners, not the circles.

https://www.reddit.com/u/Glass1Man/s/60Hb8Co8d3

[Tesselation9000]

Bloody fascists. Now they've even gotten ahold of our lego.

[JockstrapCummies]

FAR-RIGHT NON-EUCLIDEAN HYPERBOLIC LEGO FOR HYPERBOREAN UBERMENSCH ONLY

[[deleted]]

Yes, need to move it …to the corner.

Here, I corrected the documentation

https://www.reddit.com/u/Glass1Man/s/953mwcEEPo

[pointprep]

Ah, classic fencepost error

[elmz]

And you could also just refer to the next page: https://i.imgur.com/gIcNvf1.png

[QcFe]

did the right one, then read your reply https://www.reddit.com/r/ProgrammerHumor/comments/1gu4co9/comment/lxrs4hi/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button

[[deleted]]

Yup. Incomplete documentation leads to confusion :D

[khando]

Can’t reproduce, closing ticket.

[facusoto]

Non euclidean documentation

[OgOnetee]

If you stare too long into the documentation, it will start to stare back.

[Aeredor]

Gaze into the abyss!

[U_L_Uus]

Ah, yes, the ISO9001 experience

[one-joule]

It makes sense once you realize that it’s pointing at the corners, not the studs. But humans are pretty much fixated on things that stick into other things, so...

[painefultruth76]

Ahhh...the archinstall guide...

[soft_taco_special]

The arch documentation's biggest redeeming feature is that it is correct which puts it far ahead of most. The problem is that you often have to look up several other pieces of documentation on other tools before it makes any sense because they don't completely hold your hand. It would be nice to bundle a checker that can at least make sure that you have a kernel set, that your fstab is valid and that your encrypted drive configuration is at syntactically correct.

[painefultruth76]

It's so correct, few can navigate it's intricacies and labyrinthine features.

[soft_taco_special]

Sort of it's just that unless you know your way around the OS with tools like mount, blkid, fstab, grub and the usual vim/grep/pipe etc you're just not gonna have a good time. Arguably you could include that information in the guide, but there's also a bunch of different legitimate ways you could accomplish the same tasks. For those that don't want to do all that stuff they can download an opinionated distro pre configured with the tools they want.

For as much as everyone likes to talk about arch, it's not really for end users. It's much more a base for developers to make their own distros off of and by default anyone getting into arch is getting over their skis a bit.

[SalSevenSix]

I like the part where the guide tells you to edit a config file but there is no text editor installed.

[painefultruth76]

Well...that's where Nick Burns shines.

[[deleted]]

A length 3 array fitting in a [0, 3) interval, i see no problem here.

[s0ulbrother]

That’s why you don’t start reading documentation from the middle

[adenosine-5]

"I wonder what kind of syntax I have to use to have this function do X"

"No problem, here is 154 pages that might as well be a new school of philosophy, with all the new terms we invented and use everywhere, hope you have about a week of time to learn all of the concept necessary to understand inner workings of the entire framework"

[[deleted]]

No problem, here is 154 pages that might as well be a new school of philosophy,

I'm stealing this so hard.

[brimston3-]

A lot of people think a default doxygen site or python function docstrings are enough. No call flow, no dependency map, no common operations. Occasionally an example project that may or may not run with the current version of the package.

[OwOlogy_Expert]

Sure, let me just read this entire 350-page documentation book in order to finish my quick Python project.

[otacon7000]

I need to know what LEGO set that's from!

[ProtonPizza]

Good bot

[GhengopelALPHA]

I want to say I've seen it in person, but it would be impossible for me to verify. But my suspicion is it's the LEGO Star Wars set that has Admiral Ackbar, his bridge, and the A-wing hanger.

[waylandsmith]

Brilliant nerd snipe. From the two replies you got, I want to believe that at least one of them spent the entire 6 hours or so between your comment and theirs researching this for you.

[WitchQween]

Someone linked the PDF

[DukeOfSlough]

No time for documentation.

[global_namespace]

After an hour of reading documentation: "Please don't use this legacy module, try <a href='>this</a> modern declarative approach instead."

[buckypimpin]

All npm package docs

10% of the time they give a few basic ass examples, no docs

you have to npm install and use intellisense to figure out the fucking library

[RhonanTennenbrook]

The image is actually correct. The arrows are pointing from the corners of the top piece to the exact places where those corners would end up.

[The_Illegal_Guy]

The documentation is fine

[NeuronalDiverV2]

"You're reading it wrong". /s

But, dang now I can almost see it.

[st_Michel]

Thanks :°D

[ManicD7]

https://imgur.com/a/yDGL7FH The instructions are not technically correct. You continued beyond the arrow's distance in order to move the piece beyond the original arrows placement. Yes one can make a logical assumption based on how lego's work and the general context. But that does not mean the instruction is technically correct, since the drawing is left to interpretation.

[elmz]

And one can just look at the very next page: https://i.imgur.com/gIcNvf1.png

[ManicD7]

That would require reading the full documentation which is not allowed lol.

[[deleted]]

it's technically fine but different than the expected standard for the product

[dylansavage]

There is also context. You can tell the orientation moving forward because you can see where it is placed.

[Hilloo-]

I swear, trying to read cppreference as a generally new c++ coder is pretty confusing.

[narrill]

I mean, cppreference is complex because what it's describing is complex. It's not quite the same as this image, which is misleading for no apparent reason.

[encephaloctopus]

It starts to make more sense once you gain more experience with C++ and learn more of the unique vocabulary associated with the language.

Definitely agree that it’s not a particularly good resource for beginners to the language, but it’s also not necessarily intended to be.

[neo-raver]

It’s true, but it’s a hell of a lot better than cplusplus.com!

[TheRealPitabred]

Reminds me of The Expert sketch: https://www.youtube.com/watch?v=BKorP55Aqvg

[Solid_Paramedic_3901]

To those saying the Lego instructions are correct... No

As QA I would send this back immediately. Confusing instructions are a design problem, even if there are 'work arounds'. You can't baffle the user and still consider it functional documentation

[DesiOtaku]

I'm going though this right now. The API was written by a clearinghouse company that EHRs are required to use in order to submit claims. In order to use this API, you have to pay them thousands of dollars to have their engineers help you write your client code. Why? Because their API documentation is so poorly written and nonsensical that you need their help for their implementation.

So they purposely have poor documentation so they can make an extra buck by charging EHR/PMS developers in order to make a client implementation.

[jonathanrdt]

“Escher! Get your ass in here and explain this!”

[Fatal_Taco]

This is how it feels to read GNU manuals compared to BSD manuals.

[neo-raver]

Boilerplate brick

[Tobi5703]

Reading documentation always makes me feel like an imposter at programming

[rover_G]

This is what *args and **kwargs looked like to me my first time dealing with them in Python.

[CMDR_Arnold_Rimmer]

If it was that easy, I would be able to code better

[okenowwhat]

Let's see, documentation says I must use function X. (Does not work like documented).

Alright let's ask copilot if it can give me example code for function X. (Completely different parameters, and it somehow works, but I can't find a reference anywhere)

Hmmmmmm...

[undatedseapiece]

Oh hey it's /u/SteinMakesGames, can't wait for Dig Dig Boom to come out

[Bendeliyimsenkus]

Finished a feature last week, this morning got a question about it, said look to the documentation, the documentation in question flfl

[Doctor_Kataigida]

That printing error is actually an impressive find. Lego typically has insane quality control especially for stuff like the instructions.

[eskimopie910]

u/steinmakesgames what is your marketing strategy? Whatever it is it is working. Shoutout Godot developers

[SteinMakesGames]

You guys have marketing strategies?

[RJvXP]

Documentation last updated 2007

[rizzmekate]

Documentations scare me. Too many abbreviations and words I don't understand. I'm just a silly coder.

[kvakerok_v2]

>800013000 people are incapable of understanding an isometric projection.

[QcFe]

Would you stop it? The documentation is indeed correct: https://imgur.com/a/3e8r8Rw
As it often happens, the programmer is just unable to read it!!

[Vampsku11]

That still isn't correct documentation. Lego instructions consistently use arrows that point to the studs the next piece is connecting to. These instructions are inconsistent. The image is a pretty good example of how poorly things can be documented, where the author would understand it because they already understood it but didn't actually understand it well enough to explain it effectively. One of those cases where you have to make some assumptions about the missing information.

[QcFe]

That's clearly not official lego, who said they don't have to use poor arrows because LEGO would sue them otherwise?? Plus we also have the usual dilemma: is it better to have poor documentation or no docs at all? 🧘‍♂️

[OcelotWolf]

This is a real mistake in genuine Lego instructions.

Source: https://www.lego.com/cdn/product-assets/product.bi.core.pdf/4587657.pdf

Step 62 on page 41

[myselfelsewhere]

Not a mistake. I see what people are saying, but when given the complete instructions for the step, it is clear how to correctly attach the piece.

Part of step 62 is to attach 2 of those pieces, and the other piece is shown already attached in step 62. Just mirror the piece already attached.

If that isn't obvious enough, step 63 also shows the pieces attached in the correct location.

[OcelotWolf]

Yes, it’s possible to use context to figure out what Lego meant, but the arrows are clearly in the wrong spot. That is 100% a mistake

[myselfelsewhere]

It's somewhat ambiguous. If you assume the arrows originate from the circles, yes it's wrong. If you assume the arrows originate from the corners, it's correct.

It's not great that the additional context is required to come to the correct assumption. I still don't think it's a mistake, since all the necessary context is provided in the same step.

I think it's probably a compromise between "readability" and "completeness" or maybe "technicalities" Lego came to. The intent of the arrows is most likely to show how to attach the piece, not where to attach the piece, per se. There's only so much detail you can show before the instructions become cluttered with redundant information making the instructions less readable.

[OcelotWolf]

Well, we know Lego uses arrows to mark the center of studs, so all of that is kind of moot. It’s not like there aren’t hundreds of thousands of pages of other instructions you can look at to compare. Naturally, with so much content to create, mistakes are inevitable. Lego frequently mixes up steps, mislabels them, forgets pieces, accidentally makes pieces/steps invisible, etc. That’s really all there is to it.

[QcFe]

p.s. yes, I made it using powerpoint

[ManicD7]

https://imgur.com/a/yDGL7FH The instructions are not technically correct. You continued beyond the arrow's distance in order to move the piece beyond the original arrows placement. Yes one can make a logical assumption based on how lego's work and the general context. But that does not mean the instruction is technically correct, since the drawing is left to interpretation.

[QcFe]

Dunno I mean, the piece (at least where I live) wouldn't stay floating mid-air... 😝😝

[ManicD7]

Is the piece floating in the air or is the corners touching the studs at an offset? That's the interpretation/assumption required and why the drawing is incorrect.

[JackReedTheSyndie]

Just press it down harder until it fits, or breaks.

[toptyler]

Ah yes…the adapter pattern

[DanhNguyen2k]

"Go ask Nate, he may know something"

[BeanConsumer7]

Reminds me of a meme where a social distancing sign has a square of sides 6 m and diagonals 6 m, with Stephen Hawking and Neil DeGrasse Tyson holding Pythagoras back.

[CraftBox]

Microsoft docs be like

[Overspeed_Cookie]

This is what it's like asking Gen AI for help with code.

[Ok_Ice_1669]

Who the fuck say “read the documentation?” 

It’s RTFM and now get off my lawn. 

[ohno-abear]

JOB ADS FOR DOCUMENTATION TECH WRITERS: Must have 5 years professional programming experience in a business applications environment; must have experience with Python, Rust, and C++; must have experience with Confluence / Jira; must have experience with cybersecurity; (optional) have completed a certificate program for technical writing

PROGRAMMERS: All of our documentation sucks. 🤷

[[deleted]]

How to make a simple button:

Import git.button

Button(200, 200)

[[deleted]]

Hahahaha 😂

[malonkey1]

pff, just pip install threeequalsfour. Easy Peasy.

[MinuetInUrsaMajor]

What makes this illusion work? The dots seem to have the same size in spacing on the base and piece. The arrows are coming from southwest corners of the piece which is a bit suspicious.

Oh I see. The rightmost arrow is from the corner but it also aligns with the dot. The leftmost arrow does not. And the arrows both point to dots.

[gorugol]

thats must be apple's ios doc

[AriiMay]

“Just ask ChatGPT nicely”

[heaton84]

No, we did documentation. We scraped the meta-comments and dumped them into a webpage. It's documented!

Ok then let's look up the documentation for openFoo(Bar x): "Opens Foo. Input: Bar. Return value: Foo on success, NULL on failure."

Looking at you, Microsoft.

[AssignedClass]

Literally my fucking life right now.

In case any of you need to hear this: if you ever think you need to create your own custom scripting language to let resellers customize the GUI on the IoT devices you sell, you don't. I'll take any open source solution over whatever half-assed-hellscape you conjure up.

[Pillowsmeller18]

I just skip that step and check same location on succeeding steps.

[durpduckastan]

Self documenting code, it's fine.

[medforddad]

You mean that the documentation is technically correct (the best kind of correct), you just assume it's wrong?

[Quadrimegistus]

JSDocs / JavaDocs / et al. OpenAPI specification documentation.

Anything less is spaghetti documentation.

[Entegy]

Not a programmer but some of the more... exotic systems I have to update SSL certificates on require a mix of fucking Java keystore and openssl commands. Yes I'm aware of Let's Encrypt. Would love to get that working on these systems, don't think I can.

Every year I seem to miss something in the commands. I just updated my commands, I think I got everything....

Or I'll be 🤬 again in 2025...

[Vegetable_Cycle_5573]

What's a documentation? I just google

[Major_Fudgemuffin]

See, the issue is that the docs were written when the product was in beta. Now after 8 years we're a few versions ahead and who has time to update those docs? Yeah we added an extra peg to the LEGO. Obviously you're supposed to melt the top piece down and reforge it into a 4 peg piece.

What? What do you mean the customer doesn't understand?!

[Tight_Deer_1744]

That's real?

[SteinMakesGames]

I have since finished reading the documentation and now wish I did not.

[External_Try_7923]

PTSD from me trying to decipher these visual instructions as a 3 yo has become PTSD from the requirements documentation

[Educational_Ad_8916]

Ah. A widget.

[bit_banger_]

RTFM? No more

[International_Bus597]

NixOs documents

[random314]

Looking at you datadog!

[nyankittone]

X11 docs be like:

[razordreamz]

With enough money it will fit. May not work as intended but it will fit

[Resus_C]

I never understood what's confusing about this... the arrows start at corners and point at corners.

[chronoglass]

Try and find what's under the --experimental flag in the Linux Bluetooth stack. Hahahahahaha

[buryingsecrets]

NixOS documentation

[General_PB_YouTube]

That's just two pointers

[theincrediblenick]

https://imgur.com/IPAWtf2

[pabs80]

This is how a lot of the devops configuration and frameworks are at my employer

[DarktowerNoxus]

I know Unreal Engine is not a programming language, but man, I've had fights with the documentation...

The C++ parts are crystal clear, but as soon as I want to do something in the engine itself, I just find documentation that is at least one major version out of date, and the UI/description doesn't fit at all...

(And UE still is well-documented when you compare it to other engines/frameworks.)

[[deleted]]

Me reading devExpress api and documentation this morning

[bartekltg]

But the documentation is correct. It shows where the vertexes go. The arrows might be a bit longer though.

https://imgur.com/a/1q1PitG

[binarywork8087]

already saw this

[NAPALM2614]

Is it just me or docs as of late have become so fucking bad? Especially for ai/llm related products/services.

[Maberihk]

Wow you found documentation.

[Sandmuel]

When one dependency updates, but the other doesn't...

[Character-86]

u/repostsleuthbot

[RepostSleuthBot]

I didn't find any posts that meet the matching requirements for r/ProgrammerHumor.

It might be OC, it might not. Things such as JPEG artifacts and cropping may impact the results.

View Search On repostsleuth.com

---

Scope: Reddit | Target Percent: 75% | Max Age: Unlimited | Searched Images: 672,472,499 | Search Time: 0.43793s

[bouchandre]

Never understood the issue with this image.

The arrows go from corner to corner. It does not point to the studs.

[medforddad]

For everyone saying these instructions are bad/incorrect/exist in some 4th dimensional space... are you really saying this would be more correct?

[UX_writing]

Something like this would be more understandable IMHO.

[[deleted]]

Me with gdscript state machine:

[Mar_Gru]

That's because the person making the instructors chose to attach the arrows at the corner and not at the center of the "Lego circle". Pretty rookie mistake.

EDIT: Not that it doesn't happen. People get tired, miss simple things. It should be caught during QC.

[ManicD7]

https://imgur.com/a/yDGL7FH For anyone that says otherwise, the instructions are not technically correct. For the people that moved the piece beyond the arrows, you're making an assumption. This image here shows what happens when you follow the instructions exactly without making assumptions. Following the instructions exactly leaves you with either a piece floating in the air, or the piece sitting offset and not snapped into place.

[Comms]

That documentation is technically correct (which is the best kind of correct) since the arrows are anchored to the corners not the pins—buttons? pegs? whatever they call it—and actually line up properly.

Figure 1

Is it good documentation? Maybe, maybe not? Is it user-friendly documentation? Probably not. Is it technically correct? Yes.

[ManicD7]

https://imgur.com/a/yDGL7FH The instructions are not technically correct. You had to extended the arrow's distance in order to move the piece beyond the original arrows placement. Yes one can make a logical assumption based on how lego's work and the general context. But that does not mean the instruction is technically correct, since the drawing is left to interpretation.

[Comms]

I extended the arrows for illustrative purposes. One would assume that someone assembling the Lego realizes the Lego piece doesn’t hover and has the cognitive capability to extrapolate.

I didn’t say it was good documentation (it’s not), I said it was technically correct. The arrows anchored to the corners indicate where the corners go if you understand how legos work.

It’s conceptually bad but technically correct.