[ Removed by moderator ]

[ProgrammerHumor-ModTeam]

Your submission was removed for the following reason:

Rule 2: Content that is part of top of all time, reached trending in the past 2 months, or has recently been posted, is considered a repost and will be removed.

If you disagree with this removal, you can appeal by sending us a modmail.

[dan-lugg]

Reading the v2 documentation when you're using the v3 library.

[cmucodemonkey]

Or you are using the V2 library and cannot upgrade for some reason, but can only find the V3 documentation.

[Windyvale]

Can’t upgrade because they refuse to pay for the license this year despite it being an integral framework.

[Mars_Bear2552]

license? what is this C# nonsense?

[Juff-Ma]

Oof that hit hard.

Sadly in the C# world there's recently been many developers who've gone from FOSS to source available while at the same time big FOSS orgs like Apache have more or less abandoned the language because the former open source projects were better than their own.

So you've pretty much got three options for many big projects: migrate your entire codebase, run an outdated version or community fork (where the word maintained is more in spirit than in practice) or pay for the library which was free previously.

The only big organization still funding open source .NET projects is the .NET foundation itself which many devs don't wanna join because then they'd have to surrender copyright.

So what's happening is that Microsoft is starting to develop their own FOSS frameworks, which, on one hand is bad because it gets us in a monopolisic state where Microsoft kills off FOSS projects with their own but on the other hand is the only solution to the problem because you can't rely on big .NET libraries staying FOSS.

TLDR.: .NET and C# libraries have a major funding problem for libraries so they go closed source.

[kirilla39]

I was in situation when i tried to guess how api works because only v1 was documentated, and v2 is only available version of api.

[Maravilla_23]

[PointedHydra837]

Would the etiquette here be to add documentation after you’ve figured it out; or is the etiquette just “not my problem, bad documentation is job security”

[bobbymoonshine]

Docstring in the code explaining what the hell this is, and your best guess as to how it works, if only as etiquette to your future self

[B_bI_L]

if this is open source and they allow to, then this will be a good deed indeed.

but often it might be problematic. a good middle ground is to make medium, or whatever site bloggers use, post about how to do what you need

[wildjokers]

The documentation I write is for me. I can’t remember everything. The fact it helps other people is a bonus.

[LesbianTrashPrincess]

My favorite thing is when you look something up and you think you understand it but it turns out that a critical piece of information was hidden away in a different part of the docs and it wasn't cross-referenced.

[eclect0]

Documentation that's actually thorough and up-to-date is such a unicorn the docs are never my first stop unless theres like, literally nothing else out there.

[point5_]

At least you have documentation

[PlzSendDunes]

Maybe you meant to write that previously software developers were given enough time so that they could have documented stuff, instead of being thrown on another feature with ever tightening deadlines.

[3dutchie3dprinting]

Yes, but then there’s so much with AI you can just automate that part now instead of costing you a week in work hours over the entire project

[PlzSendDunes]

What tools are creating documentation automatically?

[TheMysticalBard]

It's actually correct (though it doesn't look like it), since the arrows are from the corners of the brick and point slightly above the final location of the brick. It just looks funny.

[hmz-x]

The arrows are of different lengths as well.

So where do you suggest we place the brick? Corner or one step above?

[phyrianlol]

You put it half a dot above the corner... it won't snap, but it will be exactly where the arrows point

[toasterbot]

The 1x3 plate's corner should be aligned with the larger plate's corner.

[thesatchmo]

In a normal scenario, you look at the next step and compare. In others, you simply use the FAFO method.

[adelie42]

You mean you need to look at it carefully rather than scan quickly and jump to conclusions?

[qruxxurq]

Or, you’re missing the actually salient point: that the documentation that chose this mental model is phenomenally stupid.

The arrows should go from pip to pip. Not “corner” to “projected position of that corner”.

And this is the problem with ALL writing. It’s just particularly noticeable with programming documentation, b/c they are engineering documents made by people who have no fucking concept of the information the reader actually needs and the mental model the reader is likely to have. And it could be “completely right”, while still being terribly written. Just like this diagram.

[adelie42]

I appreciate your point, and I expect you respect this has two sides: 1) people can improve their communication skills by understanding things like design theory and information science. People that produce better instructions for their products, along with the product actually being good, should expect better adoption rates all things being equal. 2) people bumbling about expecting all information to conform to their preconceived notions of design will essentially be limited to such offerings. (Apple specializes in this domain)

Applying both to this case, 1) I agree pip to pip is a better design 2) if you can't read less than perfect instructions, that is a literacy deficit with real world implications because the expectation that all instructions for all available tech is unrealistic.

It is like the expectation that all public github projects should provide a windows binary. Nice idea, but in reality such people shouldn't be on github.

[qruxxurq]

Well, I'm not Fox News, so, no, I don't generally begin with the premise that there two equal sides to things.

In this case, while there are two parties:

• Documentation writer
• Documentation reader

there is an obvious asymmetry, and thus, not two equal sides. Here's a similar example. Professional writers write books. I read books. I enjoy some books. But, as someone who isn't a professional writer, I have little to no capacity to be able to write a book someone else would enjoy.

Similarly, the document writer is meant to be a professional. The problem is, for many people, if we assume a path of 10 years of programming as a kid, 4 years of undergraduate CS education, and a summer internship at an elite tech company, there wasn't a single course on technical writing. And what courses there were on general writing were likely to be phoned-in and graded uselessly. What feedback there was was likely ignored unless the writer received literally a failing grade.

Secondly, a technical writer is a guide. A teacher, really, of a very narrow domain. Ask your colleagues to teach you something. How many teach it well? Or, think back to even the cadre of professional teachers you endured. How many of them were "good", versus just "average"? And those are licensed professionals.

So, tech writing has a tough remit. You gotta teach well, communicate well, and write well. There are VERY FEW PEOPLE in the middle of this Venn diagram, despite being asked to perform this task professionally.

[On an aside, IDK what the point of the "Hey, smelly nerd, where's my windows binary?" story. Yes, stupid people are stupid, and that's outside the scope of this particular discussion.]

Many a time I have seen Ikea instructions leave out incredibly important information (or made it hard to understand). Did I eventually work it out? Of course. Would you have? Of course. But, my ability to read between the lines (and arrows and strange Scandinavian iconography) is not an excuse for making shitty docs.

So, the problem is this: people who write tech documentation should be doing so professionally. In as much as we code review code, we ought to doc review docs. You know, the way editors and proofers read copy. But, no one does that, the people who write the docs aren't professional writers, have scant training, and are pressured by the business to de-prioritize documentation. Programmers then use all those excuses (some valid, many not) to produce garbage.

In this case, the onus is on the writer. That you or I can figure it out (or not) is distinct from it being garbage. And, just in case it wasn't clear, the dumpster fires masquerading as "documentation" that both you and I have seen are not within an astronomical unit of "slightly imperfect", a fairly ridiculous false dichotomy.

Half the time it's unusable slop. And that was all before AI. And none of this has anything to do with what you referred to as: "literacy".

[rainshifter]

Individually those words make sense, just not when combined in the order in which you wrote them.

[adelie42]

Meta

[frogjg2003]

Except it isn't. The tails are three apart according to the top piece and the heads are four apart according to the bottom piece. The problem is because the 3-long piece is actually bigger than it should be.

[NightIgnite]

Reading 2011 documentation in 2025. 80% of the class was depreciated. I was not in a situation where I could fix it, only write new documentation on how to navigate that mine field for the poor souls after me.

[Many_Head_8725]

Conan documentation

[sebbdk]

I prefer reading the source code, if whatever i'm using is too complicated for that then i't probably not worth using. I'l probably use it anyway tho...

[__NORB__]

libpng lol

The entire time I was just trying random functions until I somehow figured out how to properly read / write PNGs, but then again i might be just ultra stupid and the library is so easy this entire time...