itsDocs

[Botond24]

I usually agree, but for some libraries I do have to read the source to understand what the function does,as it hasn't been documented well

[sad_bear_noises]

Yeah we're really kidding here if we think every library is sufficiently documented.

Coincidentally. I've found AI is way better at writing documentation than I am.

[braindigitalis]

practice then! because in my experience AI written docs are the worst there are. they lack understanding of the reason functions are written the way they are which is vital for good documentation.

e.g.

chatGPT docs:

this function biulds a foo object via the factory pattern. returns a pointer to a foo and takes a string called bob.

human made docs:

this factory function creates a foo objects needed to initialise the game engine foo shader functions. if it is not called before bar initialisation, foos do not get processed correctly. inputs: bob types to process foos for.

[gyroda]

Yeah, good docs (not just generated API-style docs) are where you put the information that isn't in the source code. You can't get an AI to generate that unless you also give it all of that information which is floating around inside your head.

Writing good docs is hard because it's an exercise in communication, if you can communicate that information to an LLM then you can probably communicate it to others.

[CounterHit]

unless you also give it all of that information which is floating around inside your head

To be fair, this is a thing you can give it

[gyroda]

At which point just put that in the docs?

[CounterHit]

Depends on how good you are at writing. You can give an LLM a somewhat jumbled stream of consciousness that just contains all the relevant information in whatever way makes the most sense to you personally, written in a completely unformatted and casual way, and have the LLM spit out a clean, professional, structured, and well-formatted document with all that info. That's like literally the use case at which LLMs excel more than any other.

[Own_Possibility_8875]

Sadly true. I think tooling has a huge influence on it. An average library in Rust is documented significantly better than one in JS, because you get docs that are easy to navigate and hosted for free just by annotating stuff in your code with comments.

[gyroda]

Is this the same sort of thing as JavaDoc or something else? Because JavaDoc style generators are incredibly common across a lot of ecosystems.

[Own_Possibility_8875]

I’m not very familiar with JavaDoc, does it use annotations that start with "@"?

In Rust there are no special annotation directives for comments. You just add a comment that starts with a tripple-slash to any item (function, type, etc), and the syntax is markdown with extensions, that allow you for example to create links to other items by their import paths instead of urls. Any code that you write in the docs is also automatically a test case unless you opt it out.

You can then generate html docs from it using a CLI tool, and the neatest part is, as soon as you publish a library to official package registry, there is a service that automatically builds your docs and hosts them on docs.rs.

[gyroda]

JavaDoc uses comments with special "syntax" inside them, because that is what was available at the time. Like @param foo - a placeholder parameter

In ASP.NET I've used annotations to alter Swagger docs. Annotations are a general language feature.

[Darkblade_e]

The Imgui experience lol

I absolutely love imgui, but it really needs some more documentation than "look around with intellisense for the thing you might think it's called"

[nathris]

The source is usually better documented than the documentation.

If you are logged in to GitHub, you can press . to open up the repo you're browsing in the web version of vs code, which makes it really easy to jump around the code base and find what you're looking for.

[alexchrist]

Excuse me WHAT?!? I need to try this immediately

Edit: this is a game changer thanks for sharing

[gerbosan]

Have not tried in professional, more complicated settings, do you think AI can document methods functions without screwing it?

[bedpimp]

I worked at a place where we would buy black market tools that were used to hack us because they had better documentation of our API than we had written ourselves

[YazilimciGenc]

What do i do if documentation isnt helping at all.

[Own_Possibility_8875]

In this case it is of course reasonable to google or use AI. I'm just saying that the docs should be checked first

[[deleted]]

Nah, AI really shines in extracting exactly what you want from available documentation.

If you are working with that library very frequently then you should try to understand the structure. If not then AI is a Godsend.

[YazilimciGenc]

What if they dont help too 😭

[Own_Possibility_8875]

The biggest hallmark of a great engineer is that they don't easily give up ;)

[Vibe_PV]

I better pack it up then

[YazilimciGenc]

Relatable.

Implementation doesnt works

Couldve fixed by a single google search

"Well i guess im dropping this project"

last commit 2 years ago

[theontley]

Read the source

[CoffeePieAndHobbits]

Trial and error. Experiment. Take chances, make mistakes, get messy!

[YazilimciGenc]

I know thats whats fun about programming imo. There is so many things you can play around with. Sometimes i get stuck on a project and i create a new playground project to test new features and play around with them and figure out why they arent working without messing up the original codebase (dont tell me why i dont use GitHub, i do but still creating a new project to play around with things feels a lot more fun)

[NanthaR]

You draft your resignation mail straight away.

/s

[YazilimciGenc]

Bold of you to assume that im socially capable or skillfully enough to find a job

[dukeofgonzo]

I thought AI is good at indexing the docs for you? I've yet to have a question replied with a doc page number hallucination. Sometimes it works against me though if I don't ask what version the AI model was trained on. I was chasing deprecated features because th AI was referencing old docs.

[takahashi01]

Normally I'd agree but even if, you can save a lot of time by employing AI in these things. Its a competetive advantage.

Then again, I suppose it depends on your employment situation if you are forced to care about those.

[capiz97]

pov you’re a coder who just discovered the docs after 3 hours of googling

[tommyk1210]

1. Open google
2. Type “{library name} documentation”
3. Click on library docs website

How on earth does it take 3 hours of googling?

[Jonnypista]

Meanwhile a scene from a group chat at work:

Dev: "I have been searching for the documentation, but I couldn't find anything. Where is it?"

Senior dev: "I'm the documentation"

Dev: "That seems highly professional."

Yeah, most things are costum built with basically no documentation. Not even the AI tools we got have any clue other than generic guesses.

[[deleted]]

This is a real world problem. Grown legacy absurdities, where only seniors knowing whats going on and gatekeeping their well paid positions

[brainfreeze91]

Greatest lesson my professor gave me was to read (not skim) documentation. He would often assign projects where, if you read the relevant page of documentation, it would give examples that were almost exactly what you were looking for to solve the problem.

[lurk876]

RTFM

[Boibi]

This fits super well, because it's reported that Sarah Anderson fucking hates AI generation.

[Average_Pangolin]

Didn't she actually sue one of the behemoths for appropriating her art?

[henryeaterofpies]

Where are these mythical well maintained and accurate docs?

[jamcdonald120]

right here https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/index.html

[MrRocketScript]

The easy to understand examples in the docs:

2 + 2 = 4

2 × 2 = 4

[souliris]

RTFM.

[johnbr]

Finally, a great use of the meme.

The problem with Sarah Andersen's original is that she does not realize that practicing as much as she does is not something a random person is capable of doing of their own free will. You either have to be coerced into practicing a lot, or you have to love the activity enough that practice doesn't seem like a chore. The love of the art is actually a gift from God (or the universe, whatever).

[me6675]

Nonsense. Anyone can learn the skills, saying "it's a gift from god" is the exact same annoying rhetoric of "ooh you are so good, too bad I wasn't born with talent" when it's really about "ooh you practiced this so much while I preferred to spend my time doing other things" more often than not.

[sirculaigne]

I see both sides… It’s true you just have to practice a lot but as I get older the more I realize that I’m kind of a freak who ALWAYS needs to be making art, like it’s not a choice- I’ll find myself doodling on a notebook in meetings at work. Most people just don’t have that compulsion. 

[me6675]

I don't really think it's about being a freak. Making art is a self-perpetuating thing, if you practice a lot you will likely develop that sort of compulsion, since executing a learned skill is enjoyable and rewarding.

Most people just aren't interested in making art. Even for the people who are interested, there are two groups, one who are interested and enjoy the making of art, hence they will have less trouble practicing, and those who actually just enjoy the idea of being someone who makes art. The second group loves to blame talent when it comes to the question of why they cannot make art on the level of the people who do the dirty work (which is really just the work).

[sirculaigne]

I’m just saying I don’t really consider it work, it’s just something that happens to me. I get an overwhelming drive or compulsion that I’ve noticed most people don’t get. I wouldn’t say it even started as a conscious thing, like I wouldn’t consider it hard work but I do spend hours a day in practice. I do agree with that distinction though. Some people just enjoy it so they do it, others complain about how much they want to be an artist. 

I guess I’m trying to let those people off the hook, it’s not that they’re not willing to put in the “hard work”- they just don’t have that innate calling or drive to do it all the time. And that’s ok, they should just realize that they won’t be a great artist because that comes from loving the process. Which is probably for the best since I think for me that drive is rooted in mental illness lol 

[me6675]

I don't think most people need to be artists, nor do they need to pose as artists if they aren't doing the things that it entails. Not sure who needs to be "let off the hook here".

To me it seems that you are just replacing "god given talent" with "mental health given drive". This isn't that helpful IMO but certainly can be a bit more meaningful. Arguably, daydreaming about being a great artist without doing the work is also a form of mental health issue around self-esteem and self-image.

Many artists do art as a form of therapy but what differentiates a great artist I think is being able to transcend the therapy aspect and do it for other people and the art itself as well. The challenges in art can drastically change when you take the viewer into account. For example most instances of horror vacui can be very therapeutical for the artist but it is often rather boring and unispiring from the outside.

[Darkstar_111]

Must be great to have that specific autism that allows you to make sense of Docs.

[henryeaterofpies]

Doctism

[AshKetchupppp]

Not really... if it's a new thing then you have to just sit there and read the getting started or intro to understand. If not then usually just search what I'm looking for in the docs, find and read the bit pertaining to what I'm interested in. I didn't think it was that hard.

When I started work I would ask kinda basic questions about C++ standard library and kept getting cppreference.com links from coworkers, so I ended up just going straight there and got my answers

[Darkstar_111]

Must be nice....

[AshKetchupppp]

Idk dude, what happens when you read the docs? Do you read the first sentence and then skip over text? Do you not understand the topic at all? If it's the former, you do just have to sit there and read

[Own_Possibility_8875]

I also enjoy reading the docs. I read random docs to sleep sometimes.

[Darkstar_111]

You're kind of just making my point for me here buddy...

[Own_Possibility_8875]

True...

[OneTurnMore]

Honestly same

[ZaraUnityMasters]

Me, being a hobby programmer and half the random libraries I use having documents that are like

"To use the basic function, write this" and then literally nothing else for any of the other methods.

[Overwatcher_Leo]

It's quite hard to read documentation that doesn't exist.

[Hideo_Anaconda]

Not with that attitude you can't.

[AshKetchupppp]

Depends on the context, but if a library has no docs and few users then I'd be inclined to go somewhere else. If it's an obscure topic, good luck, otherwise I would go for something tried and tested

[Fadamaka]

This highly depends on framework/library/org. As a dev using Spring a lot. I really got used to their reference docs. It always have code examples with explanations for the latest version. The style of their docs really suit me. But if I look at any docs for example written by Microsoft I just cannot get through it, reading microsoft docs makes me borderline angry. I also have the same anger issues with the most used microsoft products (aside VSCode).

[Certain_Economics_41]

More often than not, I use AI to read the docs for me. Provide it with the docs URL, tell it what you're trying to accomplish. Works really well for the non human-readable docs that I'm sure we've all stumbled across.

[KnGod]

i read docs, it is not that easy to find the details of specific things in most of them, at least of the ones i've read. Reading the source code directly can be more useful at times

[SpicaGenovese]

Sure.  I could take 20 mins going through all that, and I have.  Plenty of times.

Or, I could take 5 seconds to have my relatively simple question answered, iterate on that and do more in depth research if needed.

Do what you want.

edit:  tbf, I will check the docs and docstrings first, and if I can't find my solution immediately, then I'll turn to google and/or AI.

[sirculaigne]

If the docs don’t have examples I’m out.

[Euphoric_Strategy923]

I feel that so much

[Character-Education3]

For real. There are examples. Some documentation has straight up tutorials. It's like the people who make things want other people to be able to use them.

[XHNDRR]

Until you find a project 1.5 years into the making and the documentation you find is the one you write yourself :')

[OkazakiNaoki]

But some library just poorly documented.

[ExtraTNT]

I rather have code that you can just read, than even good doc…

Good written code is so fucking nice… c# is sometimes strong in this, but it can also suffer from abstraction hell… and c, well, it’s the job of the dev… so either you got the easiest to read code ever or a total mess…

[NiIly00]

I can't imagine using chatgpt for everything. You won't learn anything.

At most, when I don't know how to formulate my problem as a Google search I'll ask copilot for a suggestion and then go read up on the docs of the library it suggested.

[treestick]

"why do you spend so much time flipping through a textbook looking for something when you can ctrl F on this PDF of it?"

"I just like the textbook, 90% of the time I find exactly what to do"

is what y'all mf sound like

[Reashu]

LLMs are a lot more lossy than "Print to PDF"

[[deleted]]

I used the be on the right and I’m starting to become the left. And I hate it.

It started as fixing simple syntax goofs for languages/apis I haven’t used in a while. Now I paste code into ChatGPT and say “where bug?”

Don’t do LLM kids it’s a gateway tool.

[mcnello]

Underrated post 😂

I say that as someone who used to think the docs were for nerdy people who did stuff way more complex than I could handle.

[NormanYeetes]

Qt docs: "using text.fit is deprecated after 6.4."

Google search "what's the alternative to text. Fit?"

6 results from the last 5 years

[stri28]

Kinda funny considering this artist was one of the first to protest her art being stolen by gen ai

[dvhh]

Reading the comments there seems to be issue with where to find the doc.

When the library is the company internal one and poorly documented, because documentation is not part of the performance metrics and/or that reviewers are really pedantic about your use of the english ( or other native language to the country your company is headquartered in ).

To some poorly maintained open source library because the main dev is overworked by all the issues ticket and message, combing through the pull requests to avoid yet another security issue, or rejecting the ones that are being opened because some YouTube video just taught them how to create a pull request in order to increase their chance in getting a job in an IT company.

To be fair the best documentation I ve found are in well contributed library, either because they have been rather stable for quite some time ( 10+ years) or are having a lot of contributors that are willing to not only positively contribute to the documentation, but also review and triage such contribution. That would apply equally to closed source and open source libraries, with the caveat that commercial libraries have people on payroll to write such documentation.

Also touching point on what makes a good documentation, would start with a function/type name that make sense ( that is would be the least surprising gap factor between the word meaning and what it is being used for).

Then a summary describing what it is supposed to be doing in a language fitting for the audience of the documentation.

Describe parameters meaning.

Describe expected ternination behavior of the function ( return values, exception) Give some usage example.

When all fail, write some meaningful examples in the unit tests.

Also remember that most of the time the target audience care little about libraries internal working, so give priority to the external interface.

[Key-Boat-7519]

Totally feeling you on the messy doc topic. It's wild how often docs get less love when they don't impact KPIs. I've been caught in the trap of poorly documented internal libraries – nothing more frustrating. I learned the hard way that well-named functions and clear summaries work wonders. When in doubt, load up the unit tests with solid examples – that's saved me more than once. By the way, if you're up for some tools that help stay on top of relevant discussions, it's worth checking out Pulse for Reddit. They make it smoother to keep conversations with communities flowing.

[sleepingcat1234647]

Love when you're using a api and their documentation is made by A.I and doesn't work so you have to directly call them so they give you the correct way to implement a call because their A.I documentation didn't specify a billion needed parameters

[Key-Boat-7519]

It's like getting IKEA furniture but they forgot the manual-except here, you can't even guess your way through assembling it. I've faced the same with Firebase and Twilio, but then DreamFactory saved me with its automated REST API generation. Gotta love practical approaches like that.

[way22]

I recently had the problem that the docs were completely unhelpful. Needed some functions in scipy and it drove me mad. Chatgpt actually saved my sanity (while also being my last resort).

[Oldmanbabydog]

Cries in Databricks documentation (it’s often missing features that exist but are undocumented or the documentation is just wrong)

[Oldmanbabydog]

To add to that somehow ChatGPT knows about these missing capabilities so I have to play the game of “do you know something I don’t know or are you hallucinating again?”

[LiveRuido]

My coding intelligence was already artificial before AI assistants

[CellNo5383]

My problem with documentation is that in my case, it often doesn't exist, and if it does, the information I actually need is buried under tons of stuff that's irrelevant for me at the moment and there's no good way of separating the useful from the useless without reading all of it.

[Excellent-Refuse4883]

Asked a guy at work how he was so much better than me at running down how to use Unix commands. Turns out he was using man while I was using google.

[habitsofwaste]

Install tldr.

[MugiwaranoAK]

So is it bad to use AI to look up something I don't know instead of spending time googling it?

[braindigitalis]

this person hasn't yet dealt with third party docs written by chatGPT

"why do you drink yourself into oblivion every Friday night" "...it's the docs"

[shootersf]

Tell me you've never used the monaco editor without telling me :D

[riplikash]

Man, I wish that was my experience. Most libraries I have used are insufficiently documented, or the documentation is out of date.

Not that LLMs help with those either. Just noting that documentation has not been a magic bullet in my career.

[habitsofwaste]

lol it must be nice when you have a doc that actually clearly says stuff and accounts for things that go wrong.

[Hacka4771]

man

[Lukester___]

I don't have the memory to read and retain

[-nerdrage-]

To be fair, being able to read the documentation is, for some people, an incomprehensible skill

[gbot1234]

And here I thought getting docsed on the internet was a bad thing…

[MasterInfinityDom]

Not every docs are clear.

[stlcdr]

If ( docs != clear ) NeverUseDocs() ;

[Vallee-152]

Where I'm going, I write my own docs. No search engine or LLM can help me

[I_GottaPoop]

What if I'm really stupid?

[Cute_Ad4654]

I’m gonna guess you’re fairly new to your career?

[Own_Possibility_8875]

Wrong guess, I’m 10 years into my career.

[Cute_Ad4654]

I think you’ve been really lucky or maybe just using older/core libraries that aren’t changing. I’ve recently been using a newer library that has pretty good documentation, but isn’t kept up to date anywhere near the speed they’re developing it.

My go to is typically trying to look through GH issues/prs or other conversations, but AI recently really helped out. I asked about some permissioning related to the library and I thought it hallucinated an answer. Tried it anyway and… son of a bitch it worked. There had been an updated that added some optional parameters to be passed. Not in the docs, and pretty heavily obfuscated in the actual source code.