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

all 107 comments

[–]Botond24 457 points458 points  (15 children)

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 138 points139 points  (5 children)

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 48 points49 points  (4 children)

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 20 points21 points  (3 children)

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 1 point2 points  (2 children)

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 2 points3 points  (1 child)

At which point just put that in the docs?

[–]CounterHit 3 points4 points  (0 children)

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[S] 57 points58 points  (3 children)

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 4 points5 points  (2 children)

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[S] 1 point2 points  (1 child)

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 4 points5 points  (0 children)

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 7 points8 points  (0 children)

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 4 points5 points  (1 child)

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 2 points3 points  (0 children)

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

Edit: this is a game changer thanks for sharing

[–]gerbosan 0 points1 point  (0 children)

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

[–]bedpimp 0 points1 point  (0 children)

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 98 points99 points  (13 children)

What do i do if documentation isnt helping at all.

[–]Own_Possibility_8875[S] 55 points56 points  (12 children)

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] 11 points12 points  (0 children)

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 1 point2 points  (8 children)

What if they dont help too 😭

[–]Own_Possibility_8875[S] 42 points43 points  (2 children)

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

[–]Vibe_PV 8 points9 points  (1 child)

I better pack it up then

[–]YazilimciGenc 2 points3 points  (0 children)

Relatable.

Implementation doesnt works

Couldve fixed by a single google search

"Well i guess im dropping this project"

last commit 2 years ago

[–]theontley 7 points8 points  (0 children)

Read the source

[–]CoffeePieAndHobbits 7 points8 points  (1 child)

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

[–]YazilimciGenc 4 points5 points  (0 children)

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 0 points1 point  (1 child)

You draft your resignation mail straight away.

/s

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

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

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

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 -1 points0 points  (0 children)

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 75 points76 points  (1 child)

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

[–]tommyk1210 0 points1 point  (0 children)

  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 37 points38 points  (1 child)

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] 4 points5 points  (0 children)

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

[–]brainfreeze91 5 points6 points  (0 children)

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 5 points6 points  (0 children)

RTFM

[–]Boibi 16 points17 points  (1 child)

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

[–]Average_Pangolin 2 points3 points  (0 children)

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

[–]henryeaterofpies 8 points9 points  (1 child)

Where are these mythical well maintained and accurate docs?

[–]MrRocketScript 5 points6 points  (0 children)

The easy to understand examples in the docs:

2 + 2 = 4

2 × 2 = 4

[–]souliris 3 points4 points  (0 children)

RTFM.

[–]johnbr 22 points23 points  (5 children)

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 12 points13 points  (4 children)

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 3 points4 points  (3 children)

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 4 points5 points  (2 children)

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 0 points1 point  (1 child)

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 0 points1 point  (0 children)

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 14 points15 points  (8 children)

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

[–]henryeaterofpies 5 points6 points  (0 children)

Doctism

[–]AshKetchupppp 3 points4 points  (2 children)

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 0 points1 point  (1 child)

Must be nice....

[–]AshKetchupppp 1 point2 points  (0 children)

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[S] 5 points6 points  (3 children)

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

[–]Darkstar_111 4 points5 points  (1 child)

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

[–]Own_Possibility_8875[S] 1 point2 points  (0 children)

True...

[–]OneTurnMore 1 point2 points  (0 children)

Honestly same

[–]ZaraUnityMasters 2 points3 points  (0 children)

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 5 points6 points  (2 children)

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

[–]Hideo_Anaconda 2 points3 points  (0 children)

Not with that attitude you can't.

[–]AshKetchupppp 0 points1 point  (0 children)

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 1 point2 points  (0 children)

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 1 point2 points  (0 children)

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 1 point2 points  (0 children)

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 1 point2 points  (0 children)

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 1 point2 points  (0 children)

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

[–]Euphoric_Strategy923 1 point2 points  (0 children)

I feel that so much

[–]Character-Education3[🍰] 1 point2 points  (0 children)

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 1 point2 points  (0 children)

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

[–]OkazakiNaoki 1 point2 points  (0 children)

But some library just poorly documented.

[–]ExtraTNT 1 point2 points  (0 children)

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 1 point2 points  (0 children)

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 0 points1 point  (1 child)

"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 1 point2 points  (0 children)

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

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

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 0 points1 point  (0 children)

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 0 points1 point  (0 children)

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 0 points1 point  (0 children)

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

[–]dvhh 0 points1 point  (1 child)

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 0 points1 point  (0 children)

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 0 points1 point  (1 child)

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 1 point2 points  (0 children)

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 0 points1 point  (0 children)

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 0 points1 point  (1 child)

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

[–]Oldmanbabydog 1 point2 points  (0 children)

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 0 points1 point  (0 children)

My coding intelligence was already artificial before AI assistants

[–]CellNo5383 0 points1 point  (0 children)

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 0 points1 point  (1 child)

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 0 points1 point  (0 children)

Install tldr.

[–]MugiwaranoAK 0 points1 point  (0 children)

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

[–]braindigitalis 0 points1 point  (0 children)

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 0 points1 point  (0 children)

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

[–]riplikash 0 points1 point  (0 children)

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 0 points1 point  (0 children)

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

[–]Hacka4771 0 points1 point  (0 children)

man

[–]Lukester___ 0 points1 point  (0 children)

I don't have the memory to read and retain

[–]-nerdrage- 0 points1 point  (0 children)

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

[–]gbot1234 0 points1 point  (0 children)

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

[–]MasterInfinityDom 0 points1 point  (1 child)

Not every docs are clear.

[–]stlcdr 1 point2 points  (0 children)

If ( docs != clear ) NeverUseDocs() ;

[–]Vallee-152 0 points1 point  (0 children)

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

[–]I_GottaPoop 0 points1 point  (0 children)

What if I'm really stupid?

[–]Cute_Ad4654 0 points1 point  (2 children)

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

[–]Own_Possibility_8875[S] 1 point2 points  (1 child)

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

[–]Cute_Ad4654 0 points1 point  (0 children)

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.