6 ms·
I've written so much documentation over the years, and humans always come and ask me questions that the documentation answers, but never ever read it.
by ang_cire 4mo ago
I've written so much documentation over the years, and humans always come and ask me questions that the documentation answers, but never ever read it.
- hilariously 4mo agoRight, this seems like an obvious conclusion - what is the outcome of the person writing the docs in either case: 1. Immediate better output from the machine OR... 2. Being sidelined for career promotions because you spent so much time making sure documentation was accessible while everyone knows they can ask you instead of reading it, and you will answer.
- deleted 4mo ago[deleted]
- rufo 4mo agore: #2: I'm in this description, and I am anguished by how much I do not like it. (reference: https://knowyourmeme.com/memes/im-in-this-photo-and-i-dont-like-it https://knowyourmeme.com/memes/im-in-this-photo-and-i-dont-l...)
- hilariously 4mo agoIt's bad for us, but I imagine the tech writers feelings are even darker. They spent years being demonstrating how important good docs were, nobody in management cared, they were mostly laid off and discarded before there was even a credible replacement available.
- tstrimple 4mo agoOne of the clients I’m consulting with has one of the best cloud onboarding docs I’ve ever seen. Lays out exactly the services supported. Who does what pieces. What is self service. They break out latency differences between the cloud environments and on-premises. A serious amount of good work that’s incredibly useful working within their system. I use it frequently. Their head of cloud engineering has a permanent “away” message on Teams pleading with people to check the cloud docs first instead of just asking him directly. I would be frustrated too.
- reaperducer 4mo agoIt's been this way since the beginning. That's why Usenet is full of posts reading "RTFM." For some reason, instead of telling people to do that, which solves the problem, we just stopped writing manuals altogether.
- deleted 4mo ago[deleted]
- marcosdumay 4mo ago> which solves the problem Did it solve the problem? If so, why people had to keep repeating it everywhere the entire time?
- reaperducer 4mo agoDid it solve the problem? If so, why people had to keep repeating it everywhere the entire time? Because people are lazy, or new, or for some other reason turned to asking questions of strangers in a public forum rather than making the small effort to look for the solutions on their own. It's the same reason that Let Me Google That For You was invented.
- noufalibrahim 4mo agoYup. Claude will rtfm. Most humans won't.
- fer 4mo agoIf you tell it to. Otherwise you might get the classic "You're absolutely right – I made that up. Let me look at the documentation"
- freedomben 4mo agoBut you can tell it to once (in CLAUDE.md for example) and it will nearly every time (it's getting much better at that). Since opus 4.7 (which I consider a downgrade overall) it's been much better at following CLAUDE.md . I even have an intentional contradiction in my user-level CLAUDE.md and the project levels, so I can tell which one is taking precedent or if both are disregarded, and it follows at least one of them most of the time, and it follows the local one 95% of the time.
- ben_w 4mo agoWhile they absolutely do fail as you say (though in my experience not by default), this failure mode is still a massive improvement over the frequent human case of guessing based on the function/class/property/argument names. Now, a really good human collaborator who reads all the stuff and thinks carefully, that was still better than what I saw from AI models at the start of this year. But I've also worked with my share of idiots, and been one too. I'm not going to get into if *current* models can or can't reliably do any particular thing to any particular standard; previously my comparison was the same conversations with regard to video game computer graphics in the 90s always being "photorealistic" when they really weren't*; now, I'm starting to feel such discussions have the same vibes as Tesla fans insisting that "FSD-{insert current version here} solves all the problems and is a real breakthrough and the Rototaxi will totes conquer the marketplace this time for real bro, just one more version bro", etc. * https://archive.org/details/nextgen-issue-26 https://archive.org/details/nextgen-issue-26
- moregrist 4mo agoSometimes you get lucky and it both looks up the documentation and then ignores it and makes stuff up.
- scottlamb 4mo agoWhen someone asks me a question that is or should be documented, I like to ask where they looked for it (link or search query). * Sometimes, this prompt is enough for them to find the answer. * Sometimes, they tell me a spot that makes sense to them, and I make it have the answer. (Maybe just by adding a cross-reference.) * If they refuse to look at the docs, I can't help them.
- Macha 4mo agoThe answer has always been “I asked Bob and Bob half remembered you worked in it once”, without any attempt to look for info, in my experience :(
- christoff12 4mo agoThat's when you direct them to the docs. People rag on StackOverflow for being mean, but it was a good training ground for developing habits that satisfy the social contract of professional spaces.
- scottlamb 4mo agoWhen I get that, I just repeat the question "where did you look in the docs?", or just "go look at the docs now" if they're really dense. I can't help them until they have a better answer. It takes a few tries before they internalize that they need to have a doc link before expecting my help. Once they do, I might take the next step to saying "here's the answer; can you update the docs so the next person doesn't have to ask?" And it might take a few tries before that sticks too. My goal is to eventually turn them into someone who evangelizes the docs themselves. When I write peer reviews for my colleagues, I describe their attitude toward documentation. If that's "they refuse to open the docs, frequently wasting their colleagues' time", it's not gonna go well. If it's "they make nice doc edits after I ask them", a little better. If it's "they proactively maintain the documentation", better still. Of course all this is for stuff that one could reasonably expect to be documented. Help thinking through a design problem or debugging their in-progress PR is generally a different situation.
- wafflemaker 4mo ago
- p2detar 4mo agoExactly. I recently found out I can use Atlassian‘s ROVO to ask questions against our Wiki and Jira. I now forward consultants to ROVO first and only if they can’t find an answer then I’d look at their questions. Saves me a good chunk of time. They never read my docs otherwise.
- Xcelerate 4mo agoI’ve recently had a massive productivity boost in my Claude workflow simply by asking it to search for and review: relevant PRs via `gh` search, relevant Slack threads, relevant Confluence pages (+edit history), relevant Jira tickets, relevant Sharepoint docs, and relevant Teams transcripts. I ask it to do this comprehensively before the task, during the task, and after the task. It feels like a superpower.
- onlyrealcuzzo 4mo agoFor me, the primary purpose of documentation is to help myself in the future. I don't view it as something I'm writing for someone else anymore. Ultimately, I think that's helped me write better documentation. Writing for an imaginary audience is typically harder than writing for a concrete one, and things you might think "someone else" might need to know - they either 1) don't, or if they do 2) won't read your docs anyway, most of the time.
- deleted 4mo ago[deleted]
- semiinfinitely 4mo agoTurns out all this time you were writing for AI to read!
- greenie_beans 4mo agogood thing i've been writing for myself all along
- forshaper 4mo agoAt some point I started to include jokes in documentation to encourage people to read it. For the most part, this only entertained whoever the knowledge or project admin was.
- IshKebab 4mo agoVery often that is a sign of poor UX, or that the documentation is in the wrong place.
- taeric 4mo agoIf it helps, I have found the attitude that writing is mostly for the writer to be healthy in continuing the practice. And it largely tracks with how I feel I have had better understanding of things I have documented than those I have not.
- hgoel 4mo agoAlways fun collaborating with someone on a project and having them surprised you actually read their documentation and checked out their code instead of expecting them to explain everything from the ground up.
- hennell 4mo agoI have a pretty decent readme on all projects, and a /docs folder for key areas that need specific instruction on complex ones. My boss was looking at them, but even the simple ones he was pointing claude at it and asked it to make a document explaining it. Then he'd send me the document and ask me to check if it was accurate. I added a line to the last page "this is an ai summary and may contain mistakes. Use the project readme for validated information" and told him it was grand.
- vkou 4mo agoIt's good that you're helping to pad your boss' CL and doc output count. His OKR for IC contributions on top of his management responsibilities won't fill itself.
- verdverm 4mo agoSame, but at least I benefit from my own docs when I revisit code, and now my agents do. These days they do the writing for themselves anyway, I get to review and think about the big picture. I'm def happier this way
- spiderfarmer 4mo agoHow searchable is it.
- jayd16 4mo agoIt's survivor bias though. If they read it and did the thing and never bothered you, you wouldn't notice that.
- isityettime 4mo agoYes and no. If people read the docs or performed good searches, the questions asked would primarily consist of underdocumented questions, or questions about relatively novel problems. You can still get a vibe for whether the docs are widely read that way.
- qsera 4mo agoThis is not very surprising. The docs you write can only help if the person who is reading it have the same mental model of what ever thing that is being documented. Because the questons they want answered arises from what ever little subset of understanding they have of the thing. And this could be different for different people. And this is why LLMs are great for looking up docs. It makes any docs work for any one as long as the information is present in the doc.
- pixl97 4mo agoAdding to this, if an LLM can't get the right answer from your docs, its your docs that are bad.
- coldtea 4mo agoNah, it's also just as well the LLM that's not smart enough/hallucinates. You can see it often reading the code wrongly (and the code is the canonical description of the program, no room for interpretation). Or inventing non-existent APIs. Or not being able to count the "r" in bluberries. And suddenly, the only way for it to get the wrong idea from your docs is the docs themselves being bad?
- casey2 4mo agoC compiler error authors say the same thing.
- smusamashah 4mo agoI think it was Joel Spolsky's book "User Interface Design for Programmers" where one of his strong points was that nobody reads manuals. Documentation isn't any different. And on the article's point (the title at least), I write stuff for LLM more freely because they will not care if what I have written is complete garbage. I can't do that in the documents I write for fellow humans. They will be read by them and carry more weight, and therefore require much more effort to write. With LLM, all I care about is providing enough context. May be we just need to ingrain some of that thought process in our for-humans docs.