Are people no longer capable of reading docs or long text?
Posted by earlgreyyuzu@reddit | ExperiencedDevs | View on Reddit | 395 comments
There’s a lot of complexity and nuances in projects and systems that I often find is best communicated through writing. So many meetings could actually be productive discussions if everyone had read a doc beforehand and gotten the same background on the topic.
I’ve written engineering design docs before (no one else seems to do that on my team), but then get asked to set up meetings to go over it. In the meeting, I just repeat everything in the doc. afterwards, when it’s time to implement, people still don’t seem to understand… they ask basic questions that have been directly answered in the doc
When people are new and they message me with questions, I also like to write comprehensive explanations. But I’m finding that they don’t even read them. they’ll respond with a short message, like let’s discuss in x meeting. In the meeting, I repeat everything that I had written, but in a worse form, because they keep interrupting and going on tangents instead of letting me finish.
Does anyone else experience this? What kind of place should I work at if I want coworkers who are capable of and value reading and writing?
Smallpaul@reddit
Reading is increasingly a lost art. Goes for novels too.
qwerty8082@reddit
Preach.
w00fy@reddit
I skimmed your comment, can we have a call about it? /s
tehwubbles@reddit
Claude, please summarize OPs post
a_talisan@reddit
Short answer is yes. But most the reason I can't get through documents is I have more than 20hrs of useless meetings a week and spend 2-3 more hours a day on slack with people asking me questions about stuff that is spelled out in docs... And I'm told by my manager that I can't ignore them.
Negative work is real. Organizations need to be set up so we have limited domain of knowledge and concern or communication overload results.
greim@reddit
Oh my goodness this has been my universal experience in 25 years of tech across 5 companies. I think humans just fundamentally can't absorb and assimilate that much complex information in a reading session. People either need repeated exposure, or prior knowledge the subject matter.
Also people have different mental models that work for them individually, but they suck at translating between them and reconciling them in a social setting.
Finally, there's a social taboo against explaining basic technical topics. Everyone is assumed to have the background knowledge, but in reality it's hit and miss. The people missing the key concepts dare not speak up, and you're disincentivized to explain the basics because it comes across as condescending and time-wasting to the more experienced folks, who also tend to have higher status in the org.
bizcs@reddit
I'm not interested in reading a document in the idea phase if someone is interested in my opinion to help shape the document (whether it's a design doc or a code file), and I'm primarily interested in dialogue throughput when this is the circumstance. What's faster? Exchanging texts at 80 wpm, or exchanging thoughts at whatever the average speed of conversation is?
Documents should be viewed as long living items that represent the output of thought. If you want a consult on something in the idea phase, skip the document: you don't know what to document yet. If you want a review of your idea, then document it and publish it as a draft and ask for comments.
The biggest challenge I see in this idiotic environment created where people have "sprints" and are "accountable" for progress within sprints is that everyone gets so loaded up with work to ensure they're working at maximum capacity that there's no room left for reviewing draft ideas. The only solution I know of is back pressure, where the team insists they need collaborators on a decision. This is, of course, a response to bad managers that don't leave space for this activity implicitly in how their teams operate.
Euphoric-Stock9065@reddit
Yes, this x 1000. Workers are squeezed and micromanaged to such an extent that they literally don't have time or sometimes even the permission to read/write.
> coworkers who are capable of and value reading and writing?
I'm not convinced that these people exist anymore. If they do, they probably don't bother wasting their time writing if no one is going to read it. Broken windows theory.
I've found plenty of red flags to look out for:
BidEvening2503@reddit
I think people have less patience in general.
theDarkAngle@reddit
I get on average around 4000 emails per day. I auto-archive a bunch with filters but a ton of them can't easily be ruled out as unimportant by simple criteria. I probably get another 200-300 messages (mostly public channels that I try to monitor but a fair number of direct messages too).
It's not really an issue of being able to read, but having bandwidth to even notice the thing someone is trying to put in front of me, let alone read it. I'm only a senior engineer too. The principals and tech leads are way more inundated than me.
Not saying I want people scheduling more meetings, I actively discourage that, but I tell people all the time, if they need my attention, tag me or dm me and try to clearly state what you need and why you need it. and when you need it.
hippydipster@reddit
This is a failure of delegation and leadership, IMO. In general, when the managers and leaders have no bandwidth because everyone is sending them their questions and requests, it's because they've set it up that way that everything has to go through them - or it has been allowed to develop over time.
What they need is more autonomy in their teams. More ownership elsewhere other than themselves.
whipdancer@reddit
I have to question why a Sr. Engineer is getting 4k emails. I doubt the vast majority are relevant to their actual job duties, much less requiring an actual response. If that's the norm for a Sr. Eng. in their company - that's a complete failure to manage work.
Release-Fearless@reddit
This dude is crazy for even dealing with it, hundreds of emails a day there is no human way to actually think about what you are being asked and give a good answer. This guy is where the “ok” email in response to a question comes from.
theDarkAngle@reddit
You're right and I don't even read them honestly. I just kind of scroll through and scan subjects and senders, I'll click on some but I don't fully read them, just a slightly more in depth scan of the message.
Thing is I don't really "deal" with it. At this point everyone who matters knows we don't really read all that stuff. A lot of it is just kind of rote business processes that maybe needed some dev oversight years ago but doesn't really need that anymore. That and automated notifications, but those are easy to filter. And the rest is mostly people asking questions like not being able to get an issue resolved or getting unexpected results, and occasionally it's legitimately a bug but the vast majority of that is either due to human error or not people not really understanding what they're doing.
And a fair amount of issues are also due to integrations with business partners who have extremely archaic and finicky resources (no alternatives in the market either, and we've done the best we can but for some of these partners we literally just have like one TCP socket we can connect to - it's like a godsend when they have something only very outdated like a WSDL lmao).
We've asked management to prioritize an overhaul of our internal communication practices which they've said they would do but I don't think it's high on their priorities. They could probably also mitigate it by hiring something like a product owner or product manager, at least for my team, along with a resource or two for triaging inquiries and such. But it would probably be years before a new person would actually have the tribal knowledge to do any of that anyway, unless they could find someone internally.
qwertyslayer@reddit
I was about to say, sounds like you're in dire need of a PM, then I read your last paragraph. Ouch, condolences.
freeformz@reddit
I love that I can mostly ignore my inbox. On the flip side slack is a constant barrage.
AutomaticSLC@reddit
This is a severely dysfunctional email system. I was at a company where blasting emails around for everything and every event was standard, and the entirely predictable result was that nobody saw important emails.
There is no reason anyone should receive 4000 emails per day. It’s literally impossible to get useful information out of that.
AaronBonBarron@reddit
How many are "Hi theDarkAngle", expecting a greeting before getting to the point?
no-name-here@reddit
What are the big categories among the >4k emails you get each day? 😳
theDarkAngle@reddit
Probably 50-70% automated and rote human process stuff. Most is easy to filter with zero worries, a few stubborn categories are not.
Next biggest is probably client inquiries/issues relayed to us from cs reps or another dept (20k b2b clients, some fairly demanding).
Then business partner inquiries/issues (have several partners of varying strategic importance).
Then quite a lot of internal user inquiries, other departments, etc. a lot of human error, a lot of people seeing things and not knowing whether it's a problem or not, etc.
And then ofc a lot are basically bug reports or requests for features. people are allergic to writing tickets.
A lot of it is people not knowing what they're doing or how to answer users' questions (not really their fault, combination of turnover, zero documentation of process, and evolving practices for the company).
The common themes are really poor internal communication practices which I've complained about constantly, lack of any one person or group responsible for triage which means technically everyone is supposed to have eyes on everything all the time, and legitimate technical constraints that we can't really do anything about other than phase out the old platform and/or badger certain business partners to improve their tech that we integrate with. The main platform was here long before I started and I've been tasked to create a new one so we can strangle the old one but that will take years ofc.
nonasiandoctor@reddit
As a manager I get maybe 50 unfiltered emails a day. 4000 would make me quit. At 10 seconds per email half your day would be email.
theDarkAngle@reddit
Well it was 4000 total, Im not entirely sure what the unfiltered total is. Far less. Significantly more than 50 though.
nicolas_06@reddit
Enlarge your penis, courses about cryptos + he receive a mail each time somebody say something in the hundred of subjects he follow on social media.
JollyJoker3@reddit
OTOH, there are lots of half hour videos that could be half a page of text.
BidEvening2503@reddit
We should push people to work on their communication skills.
eltee27@reddit
This includes not using acronyms and expecting everyone to know what you mean.
One-Novel1842@reddit
Acronyms actually make both writing and reading documentation easier. But for them to work, this documentation must have a reference to a dictionary where there are meanings of these acronyms.
TangerineSorry8463@reddit
JHC (Jesus Henry Christ), this exactly.
HademLeFashie@reddit
I had an incident today where I shared a recording with a team member of a 26-minute long conversation I had with an SME. He called me 9 minutes later to talk about it, saying be watched at 2x speed and skipped through some parts. Then he proceeded to ask questions that were discussed in the convo.
Sigh.
beingsubmitted@reddit
Wait... You expected this person to spend a full half hour of their time listening to a recording of you rambling to someone else in lieu of asking direct questions and getting direct answers?
HademLeFashie@reddit
Normally I wouldn't respond to comments like these, but i feel like i have to because there are lots of people who think like this.
People who eschew documentation & knowledge sharing recordings because they like to "hear it straight from the source", or because they think it's quicker. It's only quicker if you're looking for superficial answers or if you assume that the following conversation will perfectly capture the previous recorded knowledge.
26 minutes isn't that much time in the grand scheme of things if the knowledge you gain from that is worth it, and I made sure that it was. That's why I shared it. That's all I'm gonna say. Vent over.
beingsubmitted@reddit
a million years isn't too long of a time if the knowledge gained is worth it - that's begging the question, you're putting your conclusion inn the premise.
The thing is, some people just really like their own voice or think that their every thought is a golden nugget from the gods. You may even want to think of me this way right now, and you're welcome to. The point is that you told this story and seem to take it as a given that you talking for half an hour is always worth everyone's time to listen to such that it can simply be assumed by anyone reading your story.
I've listened to a lot of people convinced of that same thing who were wrong. Have you not?
If your story is "I wanted a person to listen to me deliver a half-hour monologue, but they wanted a shorter dialog, instead" , I really can't say they're right and you're wrong without at least some justification on your end, and if that didn't occur to you, that makes me more doubtful, not less.
AaronBonBarron@reddit
"Conversation I had with an SME" doesn't imply a monologue, to me it sounds like the knowledge is coming from the SME.
beingsubmitted@reddit
It's not interactive. The listener is passive, can't ask for clarification or dig deeper, and certainly there's no feedback for relevance.
I'm not saying that this 26 minute long video was absolutely a waste of time, but it feels crazy that everyone in this thread is just sitting around complaining that people won't give them undivided attention for everything they want to say without anyone asking how they know they're actually so brilliant that everyone's best use of their time is always too drop everything and hang on their every word until they've exhausted themselves.
chinniya@reddit
Yeah i always encounter this “quick call?” from colleagues who dont want to put more effort and time into understanding the matter
gfivksiausuwjtjtnv@reddit
Nobody will understand or remember anything in the future.
oupablo@reddit
Well when half of what you're presented is ChatGPT generated fluff, it starts to wear on you.
ares623@reddit
People get annoyed when their interaction with other people aren't like ChatGPT (sycophantic, always eager to do what you want).
effyverse@reddit
I would move to a cave by myself forever if ppl started sounding like ChatGPT
fadedblackleggings@reddit
Many people are so reactive, all they deserve is ChatGPT fluff.
anonyuser415@reddit
That’s a fair point—and it cuts both ways. ✂️ On one hand, people’s patience might be thinner because they’re constantly flooded with content that sounds confident but doesn’t say much. AI-generated material, especially when it's overused or poorly applied, can feel generic or detached—like it’s trying to simulate meaning rather than deliver it. 🧠
But at the same time, the sheer pace and volume of all digital information—not just AI-generated stuff—has trained us to skim, expect instant clarity, and bail if something doesn’t deliver right away. 🔎 So it’s not just about fluff, but also about how our expectations have shifted. We’ve lost tolerance for ambiguity or slow buildup. Everyone wants tight, clear, insightful—and fast. 💨
Still, there’s a real risk in dismissing AI content across the board. It can add depth or structure, especially in the hands of someone who knows how to refine and build on it. The problem isn’t necessarily the tool—it’s whether it’s used to elevate the conversation or just fill space.
(sorry)
randylush@reddit
Where are the bullet points? You expect me to read something this long with no bullet points?
Conscious-Ball8373@reddit
This is true. But also writing good documentation is a skill that most people aren't as good at as they think they are. It's really easy to write a long document that, in your head, given everything you know, explains everything brilliantly ... but which to everyone else is incomprehensible. OP might be suffering from this problem.
chaoism@reddit
And shorter attention span
BidEvening2503@reddit
Sort of. I disagree, I think the volume of information we're receiving is greater than our ability to fully digest and process.
chaoism@reddit
The ability to choose what to digest and what to let go is something this generation is learning
Once we have this ability then we can focus on the important things and have greater attention span
But yea, easier said than to be done
NeonCityNights@reddit
technically reading allows for faster information learning. I suppose the trade off is that it stresses out attention spans which have weakened
NeonCityNights@reddit
I'll just randomly answer my own comment by speculating that perhaps the future involves passing documents to a large language model and then asking the large language model the questions that would have otherwise been asked to the author.
Battousaii@reddit
This
do_you_know_math@reddit
You don’t need to comment “this”. That’s what the upvote button is for 🤝
Battousaii@reddit
Type shit
DigmonsDrill@reddit
No this is an untyped explitive
GuybrushThreepwo0d@reddit
Shit
Material_Policy6327@reddit
This
FetaMight@reddit
🔺
inkydye@reddit
Yes.
I can't answer your final question, but as to the title one, I've seen four factors:
ZucchiniMore3450@reddit
Maybe your writing is the problem?
I don't read in general because I usually spend less time to figure something out and continue with my day than to read whole documentation for all different projects I use only once.
I stopped reading it because in 80% of the cases I couldn't find solution to my questions in docs.
It is different with coworkers, I know whose docs are worth reading and whose are not.
I would need to read your documents to judge if, by my account, you are the problem or your coworkers. If you can, please send me.
I have had colleagues that are good and smart people but documentation they wrote is too verbose.
SidhwenKhorest@reddit
I actively avoid people at work who cant do anything without having a meeting about it. Its a huge time sink.
HelluvaEnginerd@reddit
Why would I read docs for 30 minutes when I can spend all day figuring it out trail-and-error style? /s
But really, most people don't want to read docs/can't focus long enough to read docs and think they can just figure it out. They usually can't.
Secretly_Tall@reddit
As a dev who’s also a writer, I think people drastically underestimate how hard it is to write effectively. Writing is inherently a linear activity, meaning you need to model the state of your reader’s mind at each sentence to properly take them from where they are to where you want them to be. There are entire books written about this.
Meanwhile every reader starts on a different page, particularly when it comes to technical stuff. Do you have to explain REST to this reader? HTTP? What level of detail is right?
It’s often easier for each reader to follow their curiosity and get their answers through Q&A. I for one am thrilled AI better enables people to answer their own question on their own level.
So sorry if no one’s reading your docs, but it’s probably a reflection of the docs.
Rostgnom@reddit
Took your advice and the books and turned them info an LLM prompt to improve an existing draft of documentation. Maybe it helps someone:
As an expert technical writer and communication strategist, your task is to rewrite the provided software documentation draft. Your primary goal is to transform it into a highly effective, reader-centric piece that anticipates varying levels of technical understanding and prioritizes clarity, accessibility, and the efficient transfer of knowledge.
Apply the following principles:
Reader State Modeling (Core Principle):
Clarity and Simplicity (Inspired by "Clear and Simple as the Truth" & "The Sense of Style"):
Adaptability for Q&A (Your Core Insight):
Tone and Engagement:
Instructions:
[DOCUMENTATION_DRAFT]
.jmking@reddit
There we go. This is it.
No one wants to read your 40 page doc full of totally pointless detail, or is way too technical or not nearly technical enough.
People tend to make the mistake of crafting the doc that demonstrates their deep knowledge rather than writing the doc that their audience actually needs.
You should write in such a way that lends itself to skimming. Anticipate the questions people often have and structure the doc from that perspective.
So many docs just get into it and provide zero context, assumes stakeholders all have the background and understand why this service or app exists (or will exist), what the goals are, etc
If you're writing a design doc and you want feedback, then structure the doc around the novel/unique/specific complexity that exists in the design and draw the reader's attention to the actual things you need feedback on.
No context, and burying the lede with a doc that hides the challenges amongst exhaustive and unnecessary detail means the only feedback you'll get is bike shedding over naming, camel case vs snake case conventions, etc
If no one is reading OP's docs, it's going to be largely because of the doc itself. People open it, give a quick skim, realize how much work you're asking them to do to fish out the details they actually care about and will instead just ask you.
binarycow@reddit
IMO the docs should be highly structured with lots of links.
I should be able to start at the table of contents, click no more than 3 links and see what I want to see.
jmking@reddit
Exactly - what is your audience likely going to need to know and want to know? Just speak that language and make all of your jobs easier.
They'll actually get value out of the things you document, and you'll have to write less and answer the same questions over and over again.
Every doc should have a goal in mind. What is reading this supposed to do for the reader? It can't be "here's a brain dump of everything" because you're making work for people. The doc should make less work for everyone, not more.
Like u/secretly_tall mentioned earlier, this is a skill and most (including myself) greatly underestimate how difficult it is to communicate effectively in writing.
I'm long-winded. I'm sure if I tossed all my replies in ChatGPT or somehting and asked it to summarize, it's come up with 2 simple, crisp and clear paragraphs to replace my 25.
binarycow@reddit
I'm long winded when I write documentation too. But it's not fluff. Everything is useful, it just might be too much detail.
To combat that, I make sure it's hierarchical. The first part of the section gives you the summary. If that's enough - you move on to the next section. If you want more detail, read the child sections.
Every section has a title. Every section is represented in the table of contents. I don't duplicate stuff - if I mention something that's described elsewhere in the documentation - it's a link.
jmking@reddit
Right, you're writing for your audience. The hierarchical approach works really well when there's a lot of content and don't want to immediately overwhelm readers
wannabeDN3@reddit
Agreed, the principle of "glanceability" of code design should apply to design docs. Reading is a cognitively taxing activity so docs should be as simple and straightforward as possible.
Thin_Sky@reddit
Tbh, I'm pretty sure the best way to learn is by doing both. If all it took was reading docs, then people wouldn't say the best way to learn is by doing. That being said, if you're completely clueless bc you didn't read the docs either, then it's a waste of time.
I find for me I read a little bit then spend a while trying and falling. Then I read some more after spending a few hours trying, when the docs actually make sense now that I'm familiar with the ecosystem. Usually the combination of those and a good night's sleep are what I need to learn something new.
Otis_Inf@reddit
Or worse: they rather spent 10 minutes writing a question and follow up dumb questions than reading the docs for 1 minute. :(
AlexGrahamBellHater@reddit
I used to be that figure it out type dummy.
I've since learned that reading the documentation or looking it up saves a lot more time and is more commendable as well
Big_Fortune_4574@reddit
I still like to figure things out.
But some things have already been figured out, so now I am better at recognizing when that is.
jepperepper@reddit
yep. htere are things in the manual that are not in the code.
example: code: step on gas, more gas goes in motor manual: step on gas when starting to make car's motor go fast enough to overcome static friction and begin moving
jepperepper@reddit
yeah just read the code, it's self-documenting
Evinceo@reddit
There's a reason RTFM has been thrown around for as long as I've been in this field.
a_reply_to_a_post@reddit
yeah but an hour of debugging can save you 10 minutes of reading TFM
rlt0w@reddit
And a minute of asking the developer can save you 10 minutes of finding the relevant section in the field manual and hoping it's updated.
InvestmentGrift@reddit
i remember in like second grade, my teacher gave the class an assignment where we had to follow a list of steps and eventually end up writing some super long essay on some bullshit.... but hidden in the list of steps, at around steps 3 or 4, it said "skip all the following steps, write your name on this blank piece of paper, and turn it it. this is a lesson about following directions".
more than half the class turned it a huge essay
darkapplepolisher@reddit
Of course, that's complete and utter bullshit. Teaching people that instructions are counter-intuitive and riddled with gotchas meant to exploit their intuition is the absolute wrong lesson.
Being able to skim material without being mislead is a service to the reader that should be expected of the writer. It is simply a bad document that results in over half of its readers arriving at the incorrect conclusion and should be condemned.
I currently work in an engineering field where our written procedures we create are expected to confirm to a strict style guide. We leverage the workers' familiarity with the syntax, structure (and potentially limited vocabulary) to maximize the odds of them completing the procedure with the least human error.
Helping people succeed through being straightforward rather than pushing them towards failure through being clever is the lesson we should be teaching students.
- Sincerely, a student who fell for the gotcha, but had the wisdom to see the wrongness in the deceit
fizix00@reddit
What if the lesson is that people who wield power will try to deceive you?
darkapplepolisher@reddit
Then I suppose I learned the correct lesson after all. I still worry for my peers who didn't.
Ok-Scheme-913@reddit
You are expected to read through an exercise's text though. I mean, even by your own advice, skimming through it should have told them that they should look out for that instruction.
darkapplepolisher@reddit
It's sometimes easy to miss singular instructions, especially when obfuscated by adjacent instructions that are non-applicable.
A well designed document would ideally involve the author/submitter axing the non-applicable sections (there are no conditional statements that the worker is required to evaluate and mark those sections as non-applicable themselves). Even if there were conditional statements that required the worker to make a determination of whether those steps are applicable, there are multiple steps that could be taken to ensure the worker performs them correctly.
We're developers, we shouldn't be compiling instructions that will never be executed at runtime, and if we do have runtime conditionals, we condemn spaghetti code with senseless GOTOs and non-intuitive branching complexities.
audentis@reddit
I had a similar thing and hate everything it represents.
It was a list of trivia questions in high school that at the top of the page had the standard blurp of "read all questions manage your time yada yada". I figure: I'll answer the ones I know already because it's all multiple choice already. Last question: "if you answer nothing except for this question with 'B', you get top marks".
Fuck that. It teaches people to be lazy and teaches them to look for easy escapes, instead of applying their knowledge.
The intended "lesson" about the value of work prep is only valid if the work actually needs prep, and a simple multiple choice trivia test isn't that scenario. It's teaching people the wrong skill for the situation.
And to prove my point, I had finished all questions before the first "full reader" had even reached the final question.
entropyadvocate@reddit
I remember that in elementary school. Except instead of an essay you had to say out loud "I am good at following directions", among a few other things. Or at least you did that if you didn't follow the directions...
Pwngulator@reddit
ChatGPT, RTFM for me and tell me what it says
SebtownFarmGirl@reddit
Now it means “Read them for me”
SubZane@reddit
The acronym is probably older than manuals
obviously_suspicious@reddit
at first it was Read the fucking manuscript
DigmonsDrill@reddit
Moses was just "read the tablets, they're not that long, c'mon"
high_throughput@reddit
Moses was like "You Won't Believe These 10 Divine Rules (from GOD) -- #4 Will Blow Your Mind!!"
ClonesRppl2@reddit
I hate that this makes me want to see what #4 is.
Big_Fortune_4574@reddit
https://i.imgur.com/vKuZXjm.gif
unbrokenwreck@reddit
I think it's a bit nuanced than most people think. I'm a fan of reading docs but it also depends on quality of the docs and how much translatable they are, whether the author has done good enough job to cover the basics and prerequisites to be able to let the readers comprehend the contents to the fullest. I'd probably try to get an explanation from a living soul if the doc expects me to just know bunch of random terminologies without any reference to what they actually mean in its context, espacially when it's so exponential that comprehending it becomes a projects of its on.
This is not new and quite prevent in companies with terrible onboarding process. Big tech is a huge example of it where teams usually operate in silos and have and job security depends on gatekeeping information.
Evinceo@reddit
Definitely cuts both ways. Great documentation isn't just a list of available functions, it's that plus an in-depth explanation of what you're supposed to do with the software and how to do it, to the point that people start copy pasting from the docs like a good Stack Overflow question.
ViKT0RY@reddit
https://imgur.com/a/LyZGzhs
Em-tech@reddit
Always has been
rlt0w@reddit
I'm thrown dozens of documents for each project. They detail all the engineering and design of a particular technology stack that I'll be pentesting on. Many times, these docs contain optional design ideas, or other implementations that were ultimately thrown out, but the docs weren't updated to reflect that. The docs might also mention the use of a technology, but then I don't see that in my testing only to speak with the dev team to find out they changed to another system. The docs might mention a particular shema for the API request, but active testing shows that the scheme is entirely different, or had several parameters renamed, added, removed, etc... I 100% of the time need to speak with developers about their documents because they are inaccurate. So yeah, most of the time a meeting is necessary.
Dry-Aioli-6138@reddit
TL;DR
raymond_reddington77@reddit
I read the title and thought yeah I’m not reading further. lol
Fidoz@reddit
There's an art to writing concise docs.
Maybe have chatgpt summarize it for the meeting?
bradsk88@reddit
This is the answer, kind of.
(I think people are burnt out on AI recommendations)
Well written documents should have several obvious "exit points".
Start with the executive summary: one or two short paragraphs that summarize everything in the doc including decisions or lack thereof. A human can do this with practice.
Next, expand slightly, for a slightly more technical audience. One paragraph for every " idea" in the doc. Give people a sense of what will be explored in the next section, while also giving them the most important takeaways.
Next, dig into the details in high resolution for the people who care about them.
-
This allows your doc to serve all audiences.
It also addresses one of the key challenges of effective communication: people often need to hear something three times before they will internalize it.
Fidoz@reddit
Yeah I mean I usually have AI rewrite my commit messages and shorten my docs (from brain dump to concise).
Logical-Idea-1708@reddit
Oh yea, that’s a great idea. We need some AI that ingests tech docs and just have people ask the AI. A Slack bot would be great idea
ivan0x32@reddit
Yes, but I'm autistic, I think the way I write and communicate in general is overly verbose for neurotypicals and they just skip over all of my carefully placed details and then have questions as a result.
So I'm kind of trying to be less verbose in general and give people short bullet points and highlights instead while providing all the details separately in case they want to read it. I still write giant documents though but I have accepted that "going-over-a-doc" meetings are necessary.
RandomUsernameNotBot@reddit
Similar to you.
I will even write the problems they will run into and then less than a day later I’m getting pinged asking what to do about that very problem.
People just don’t read. It’s especially egregious for ESL devs with big egos.
jesusrambo@reddit
AI is super helpful for boiling down overly verbose responses
You don’t have to copy paste the output, but it can be helpful to see how it changes it
fuckthehumanity@reddit
Gemini, could you please summarise OP's post for me?
OP, you need to find another job.
legendarygap@reddit
Tik tok brain
Acceptable-Milk-314@reddit
No. Usually a waste of time.
jesstelford@reddit
Yes, I 100% see this happen way too often!
But... I've found great communicators are able to tailor their message to a particular audience / situation when they recognise when their chosen format isn't landing.
For example; knowing that folks won't read a document before hand, a Principal engineer might prepare for it by using the first 15m of a meeting to do a live demo of the situation / problem / biggest areas of risk / etc. Ie; "Show, don't Tell".
Or, a Feature Owner IC might leave out a whole lot of technical details when pitching an idea to a VP, instead focusing on how it solves that VP's biggest needs right now (which hopefully align to the companies biggest needs, but that's a different discussion 😅).
Or, an IC might add an FAQ to a design doc in recognition that folks who aren't as familiar with the project may not remember everything they've read, or even where to find the right details without re-reading everything.
☝️ All of these are extra work, and none are mutually exclusive with writing in-depth documentation. But all of these skills will get you further than ever before in your career!
hippydipster@reddit
My experience with this is largely the same. I'm not very good at thinking on my feet and verbally engaging in group discussions. I go too slow. I actually order my thoughts before I begin speaking, as if I'm writing. But then people interrupt and talk over me, and whatever my plan was for expressing a complex idea goes out the window.
So, I write. And get crickets. And then in meetings I get talked over. So I write. And get crickets. And so it goes. I have 40 years experience programming, 30 professionally, and no employer of late is really getting much of that value.
cuntsalt@reddit
Same, same, same. I am physically incapable of jumping in with the vigor and loudness that seems to be expected.
I've been asked a question -- with my name used -- and someone else responds for me. Had ten minutes of a fifteen minute meeting commandeered for someone to talk about their children. Four person group brainstorm devolves into a frothy (and ultimately fruitless) back and forth between two conversation-dominators who seemed to forget the other two people in the room. PM who probably has a single pea bouncing around in their skull super into "leading the conversation" and won't get the hell out of the way to let real talk/work occur.
I'm at the point where I just sort of dust my hands off and let it go up in flames. If it takes me three times as long to do something because of garbage communication, it takes me three times as long and I will have receipts as to why that is the case.
But, yeah, sure, introverts are the ones with poor communication. 😂
hippydipster@reddit
Not only are the introverts to blame for it all, but it's also because all those people who are good at the soft skills only understand you if you speak their language.
syklemil@reddit
Yeah, I feel this. Sometimes I just go for the "well, whatever, I spent so much effort lining these thoughts up and I'm not going to throw that away" and wrench the conversation back a bit.
I can get pretty carried away in chats though.
earlgreyyuzu@reddit (OP)
Wow, 40 years and "no employer of late is really getting much of that value." That has been my biggest fear... I have that feeling frequently and I keep holding out hope that I might join a company one day where I'm able to max out that value. But I keep hitting some wall or ceiling created by those above me.
SillyTr1x@reddit
Was going to ask for a TLDR; but the answer is no.
Every-Passion-952@reddit
This is the number one waster of my time right now. Anecdotally I did not have this issue when I worked primarily with engineers age 40+
Which-World-6533@reddit
The simple truth is that reading comprehension is at an all time low.
This study https://muse.jhu.edu/pub/1/article/922346/pdf shows how bad literacy is for undergrads studying English.
The vast majority of people in the workforce have the reading age of a child. I've found it the most convincing reason yet why I am in endless meetings that could be emails.
People can't read. It's the only reason.
zackarhino@reddit
Having illiterate English majors is a bad sign...
hippydipster@reddit
I suspect reading will be replaced largely with AIs that talk and draw for us in real time to help us understand and learn. Visuals that flow with the verbal explanations to help us understand things a lot faster than reading can do. And not like those bullshit youtube videos that A) are mostly trying to keep your eyeballs there longer, B) are done poorly, and C) aren't interactive. This companion AI I envision will be engaged in back and forth with you and always with the visuals to help it all along.
Which-World-6533@reddit
Powerpoint presentations are already the easy-reader version of most documents.
Three sentences to a Powerpoint slide and a picture of a kitten doing something funny.
I fully expect to be giving out coloured crayons and sippy cups in meetings in 10 years time so I can keep my co-workers amused.
jesusrambo@reddit
I see unnecessarily technical explanations more often than unnecessarily simplistic.
These come from people who can’t see the forest for the trees, and get bogged down in technical details they think are relevant
By far the most important thing I learned in grad school was effectively communicating extremely technical presentations. The best way to do that is almost always abstracting away as much as possible.
motorbikler@reddit
We desperately need a center for kids who can't read good and wanna learn to do other stuff good too
Franks2000inchTV@reddit
I mean with age comes experience. I remember as a kind waiting for my dad to read the whole instructions for an Ikea shelf before he started building one, and thinking "Why not just start?!!"
Then one day I put together 90% of a shelf only to realize I mixed up two pieces and had to take the whole thing apart and start over.
saulgitman@reddit
I hate the "Youtubeification" of education. People default to 2 hour Youtube videos that restrict their epistemological scope to only the easiest, most basic concepts and then, surprise surprise, discover the real world isn't as black and white as the video made it to be.
Bright_Aside_6827@reddit
let me check with chatgpt
Any-Woodpecker123@reddit
Has anyone ever read docs?
fuckoholic@reddit
Can you give me a short TLDR of your post? Thanks!
Infamous-Bed-7535@reddit
Welcome in the world of LLMs. People think that they are knowledgablee as reading through their favorite model's output on any topic. In reality they do not collect real deep understanding and forgot 99% by tomorrow.
noonemustknowmysecre@reddit
Not as bad as you're describing. But I have dealt with some people not reading documentation. Things they really ought to have known. Some are spot on. But that's how it's always been.
On a related note, what has really bugged me, is this trend I've noticed where if you have any sort of communication where you have more than one question, they will only respond to the last one. Important stuff. Vital engineering requirements that hold up the project until you answer these questions sort of stuff. But the next paragraph comes or the next message and they've forgotten all past communication. Like babies with no object permeance. Or they're distracted from the first question by the second question.
Syrdon@reddit
I have found that closing on a bullet pointed list of the questions that need answered can help this when I've run in to it. Probably worthwhile to lead with the paragraph form of "we're going to talk about these x questions: bullet point list", just to see if you can get the idea of how many answers you need answered in solidly.
Salty-Custard-3931@reddit
too long didn’t read /s
Rekotin@reddit
Talent density problem.
popovitsj@reddit
In Amazon, a well established practice is to reserve the first 15-30 minutes of meetings for reading.
ButterPotatoHead@reddit
I struggle to get anyone on any team (tech, product, program, leadership) to read anything longer than a couple of sentences. I used to write up 4-6 page summaries, which were about half diagrams, and now write 1-2 page summaries that are bullet points. But it's still murder to get anyone to read them.
Call a half hour meeting and say everything that is in the document, apparently everyone is fine with that, but they're probably multi-tasking. But ask them to read 2 pages for context before the meeting and nobody will have done it.
PerduDansLocean@reddit
Wait until you figure out some people are incapable of reading a code review comment consisting of a paragraph of two sentences and a list of three options nowadays too. Watch them misread that comment, forcing you to quote yourself in the very next comment, which finally shut them up 🙄
hippydipster@reddit
You can get that experience right here on reddit.
midasgoldentouch@reddit
It doesn’t help that people tend to approach commenting as a debate. There’s been multiple occasions where a commenter agrees with what I said but the tone of the comment is argumentative, as if they’re rebutting instead.
python-requests@reddit
Can't believe I need to tell you this, but what people like you often need to realize is that sometimes even though it sounds like people are fighting you, they're actually saying the same thing as you
midasgoldentouch@reddit
😂😂😂
syklemil@reddit
That could be something of a cultural difference as well, like how US southerners stereotypically smile all the time, while russians appear to not know how to smile at all.
I try to start off comments where I'm essentially adding what I think is relevant information with an affirmative, but I still get people who seem to think that any response is argument.
jesusrambo@reddit
So you were able to distill 6 pages of information into 1 page of bullet points, that’s a huge improvement!
It does sound like there was a communication problem, but not with the readers
MoreRopePlease@reddit
Show them how to feed the doc into the AI and then they can ask the AI the questions instead of you.
txgsync@reddit
These days I just write everything important up and stuff it into NotebookLM. Then ask my dev friends to go talk to the notebook when they have questions. And come to me if it cannot answer (which usually boils down to “knowing the right questions to ask” which has always been a hard skill to master…)
It works surprisingly well. They get the journey of discovery they want and I get to write all the nerdy technical details I want. Win win. NotebookLM is crazy good. Their top complaint is that they cannot ask questions that are like 10 pages long.
davispw@reddit
When you have that meeting, try having 10 minutes of “silent reading” at the start. Everyone read the doc for themselves. Then the meeting can discuss the real remaining issues.
(If 10 minutes isn’t enough, then maybe it really is too long, or maybe you need to organize it so that most readers can understand the overview without too much detail.)
cant_have_nicethings@reddit
Yes and I responded to a wall of text yesterday with “let’s discuss in person” because I read the whole thing and I suspect the info might be inaccurate and it would be quicker to clear up with a discussion than in slack.
airshovelware@reddit
I understand completely because on reddit if a comment is so long that I have to scroll on my phone then I usually won't bother
colouredmirrorball@reddit
Tl;dr?
bsenftner@reddit
This is no body being trained in nor understanding the need for effective communications. They are like morons: you give them what they need, and they do not read it, you have a meeting to discuss and they go off on tangents and when the topic is being discussed they are not listening. All they want is to be led by the hand, given what they need the moment they need it, like children following instructions in elementary school. This is the state of the software development industry, globally too. It's a fucking farce.
bsenftner@reddit
To address this idiotic behavior, I've started placing the design documents and everything related to a project in a RAG Q&A bot and when people ask something they should know, they get "ask the project bot".
Staatstrojaner@reddit
Short answer: No.
Long answer: Noooooooo.
All jokes aside: I see it every day that juniors jump straight to an LLM of their choice instead of searching for official documentation. I'm working with .NET and the .NET docs are pretty thorough and also give plenty of examples for all kinds of stuff. I'll always go there first and in 99% of cases find my answers there.
mr_bag@reddit
Really depends on the quality of the documentation and context.
For the most part I am very much a skimmer on the basis 90% of the time there is only a very small subset of the information that's relevant to what I need to do or know about. Reading a manual cover to cover just isn't a good use of time.
I'd also say documentation is rarely at the level you need it. For a high level overview is can work, at a more detailed level it almost always not detailed enough, out of date or just wrong. I don't think I've ever come across a project/system that gets the balance quite right - even for the tools I'd argue on balance have very good docs.
redditthrowaway0315@reddit
The doc might not be well written. It depends. I have never seen any internal docs that are well written -- at best they are outdated, and at worst they are non-existent or even false. Getting a meeting and a demo might actually be a lot faster.
That's why I always put a lot of pictures and videos in the doc if it's operational.
coded_artist@reddit
I learn what I need to learn nothing more. IT, software development and programming are just too big to learn everything. Otherwise I'll argue why haven't you bothered to learn assembly, better yet why don't you do the manual thing you're automating manually. We are lazy, that is a benefit not a detriment. We automate the things we find tedious, you will likely find devs (not vibe coders) asking ChatGPT to create a summary of a doc site. I'm not going to spend a week studying the docs for what should be a 2 minute task. If you think I should I'll argue then you shouldn't be making docs because assembly exists and has docs already why are you bothering to make another tool that does what you could have learnt to do in assembly.
hippydipster@reddit
JIT learning. If I read some technical documentation a month before I need to know, I won't retain it, if I read some syntax/api specs a day before I need to know, I won't retain it.
When I need to know, I'll retain it. AOT learning of anything specific is largely wasted time.
plopaaa@reddit
I've seen many long, disorganized docs that are missing key information, filled with unnecessary technical details, and are just a chore to get through. I used to write such docs and everyone would dread reading them lol
These days, I whittle down my drafts into super short 1-2 page docs and the reception has been extremely positive. Consciously limiting the doc length forces me to be as clear & concise as possible. If any reader wants to get more details, they can just start a comment thread on the doc
coffee_beanz@reddit
In my experience, there’s an art to writing and formatting docs or providing explanations. People need to be capable of visually parsing it before they’ll actually read what you write. Then what you write needs to be digestible for that person in that context.
The easiest example is if your whole doc is one giant blob paragraph, no one will read it. Doesn’t matter how great the content is.
These are my tips:
Know your audience and meet them where they’re at. Many different teams or different functions refer to the same concepts differently or have different acronyms. Get to know that so you’re speaking their language.
Provide bullet points and numbered lists as frequently as possible.
Assume zero context. Start with providing background context needed to understand the rest of the doc. Every introduced concept should link repeatedly, consistently to other docs that contain more granular detail.
Provide visuals and analogies for building mental models. Perma links to code examples are great. Screenshots of the code so people don’t have to click and come back are even better. Both together are excellent. Diagrams with arrows and highlights or sticky notes help a ton.
Use lots of section headers and add FAQs. Keep them updated as you go.
Share docs publicly and most importantly ask for feedback before and immediately after publishing. You want to know what’s missing and what’s working well to iterate on - again, to meet people where they’re at.
Centralize docs so they’re discoverable. Don’t share a flurry of Google doc links people will never bookmark and forget. Create a handbook with one link that gets shared. Make a custom go link if y’all use that.
Easy onboarding task. Newbies update docs with whatever they found missing or couldn’t understand with their actual zero context as they’re onboarding.
Get curious and take note of why people still want a meeting or interrupt your live explanations and use that. Once people get and understand the value of those docs, they’ll evangelize. Then you’re on your way to a culture change if you keep it up.
hippydipster@reddit
Saw a list so I skipped.
StolenRocket@reddit
Some people will literally prompt an LLM for two hours to write them an e-mail that they could have written themselves in 15 minutes.
ravigehlot@reddit
I’ve always made an effort to read the documentation. But lately, it’s been hard to keep up. It takes time and it’s not just one set of docs, it’s multiple. You have to move fast too, because it’s sprint week, and tomorrow morning you’re expected to help clear blockers for the team during stand-ups. That’s part of being a good team member. That’s the company culture, right? So now, on top of everything, you’re expected to read even more documentation just to be useful. But make sure you still hit your deliverables, because the product owner is under pressure from stakeholders who want results now. Meanwhile, you’re constantly interrupted by front desk chatter, unrelated conversations, distractions everywhere. A coworker is watching YouTube all day and no one seems to care. And through all this, you’re supposed to stay motivated? Then comes the kicker: after all the long hours and hard work, you find out the company’s being acquired. All that effort? Replaced. It starts to feel like no one really cares. So how is this sustainable? How are we supposed to stay passionate, keep learning, dive deep into documentation, and grow when we’re constantly pulled in every direction? I have a life outside of work, too. Honestly, it felt easier for people in the past. They didn’t have the constant information overload, the pings, the social media, the endless distractions. Many could retire from the same company they started with. It’s just... a lot harder now for less pay.
NanoYohaneTSU@reddit
People haven't been able to consume longer than a paragraph for a long time.
I learned this the hard way when trying to explain things while interning. I explained it in detail so that there is no question.
They read a few sentences and then just ask questions instead of reading the entirety that would answer most if not all questions.
Scopes of work growing beyond a few pages are nearly impossible for most people to keep on track.
logicannullata@reddit
Yes
ElJalisciense@reddit
TLDR
FizzleShake@reddit
When answering questions, link the documentation and how you found it every time
ImSoCul@reddit
I'm a "long doc" guy as well and this is my preferred way to reason through, present, and also understand information. Most people are not
This is the crux of career development. Some people genuinely are really good at their job and can distill information from long form doc, some people are even one step beyond that- I had a well respected applied scientist who would not only read and understand but also coach me on how to better present information.
You have to cater to the bottom common denominator, and there is a lot we can do to improve our own communication. It's a similar concept to emotional intelligence: learning to understand how you respond to things (how you process information) is already a really strong step, but the target is to understand how others feel (how your presented information will land/not land). Being honest, we all have a lot of room for improvement. You can include executive summary, diagrams, link sections to different granuarities (this is the tldr; this section covers the reasoning to reach this tldr; this is source material, etc). Put the punchline clear and in bold and multiple times and limit the amount of "key information".
Watch this lecture as well https://www.youtube.com/watch?v=Unzc731iCUY
Mini-vent: I had one case where my PM complained my doc was too long, he put a table at top of my doc and told me to fill it out. I did, made it all color coded so even a toddler could interpret it, then he forgot he was the one who requested it and complained about it not capturing the right information. kms
PerduDansLocean@reddit
Yup. I draw up diagrams a lot when communicating with my PO. If I had three different figures in a diagram, I'd reference each of them using their corresponding color in the explanation text accompanying the diagram, like making the word "top figure" green if that figure is green.
ArtisticFox8@reddit
That's a highly underrated tactic. Most texts are still black and white, as if we were going to print them...
smerz@reddit
Most documents written by developers are badly written, and don't give the correct level of details. Write a top down style doc with basics up front and detail at the end. As a dev, most of the time I don't need the detail, just high level design, issues found, limitations - 2-3 pages at most - the rest I will lookup in the code repo.
Most tech docs that are extensive are still bad - Spring and Gradle come to mind - all the wrong level of detail, with few COMPLETE examples rather than snippets of code. Also, when there are 5 ways to do something - few mention which method is best in which scenario.
cuntsalt@reddit
This is a horrifying and illuminating read:
MoreRopePlease@reddit
I'm pretty sure if you read below a 6th grade level, you're not going to be on an engineering team.
Which-World-6533@reddit
I have seen so many Senior (and higher Devs) who need hand-holding when going through a technical document. Being able to give someone a document and expect them to comprehend it's contents are over.
Reading more than two paragraphs is now a lost skill.
constant_flux@reddit
I worked with a guy who had a tooth literally fall out during stand up because he didn't think brushing your teeth was a big deal.
You'll be shocked at what level of competence exists in this industry.
cuntsalt@reddit
Never worked with someone who won't read error messages? Maybe that is more of a can't.
I also work with a project manager who types exactly like this with run-on sentences and no punctuation I still have to work with her it's really hard to wrangle surely she's not reading and understanding anything I've posted that is more than a tiktok caption in length
syklemil@reddit
I think that's more about emotional maturity / security. There are some people who just can't deal with what they perceive as negative feedback, and a bunch of people who are anxious around computers in general.
(Though I wouldn't expect people who are anxious around computers to be on a SWE team any more than I would expect someone who reads below a sixth-grade level.)
cuntsalt@reddit
I dunno. Part of understanding an error message is understanding the underlying complexity. Seems understanding "multi-step instruction and complex sentences" would slot in nicely there. Which of course feeds into the emotional overwhelm... but I often suspect the root cause is closer to reading ability.
syklemil@reddit
Yeah, I'm not claiming it's 100% one or the other, but people will click away even simple error messages in a mild panic. If they get a stress response from an error message, and they're unable to manage that stress as an adult would, then I think it's both fair
As in, I think better reading abilities are good, and I also think better emotional regulation capabilities are good.
QuantumCloud87@reddit
One of the things I really dislike about working on teams is a) the lack of documentation, b) the inability of other to people to read and organise documentation, and c) the preference toward synchronous communication that ensures no one that isn’t on the call, or in the meeting, gets any value.
Documentation lives and is useful as long as you maintain it adequately. Meetings last as long as the meeting. I find it incredibly difficult these days to keep all the content of a meeting in my head for future remembering. That can’t just be me.
I feel like the desire for companies to work in sprints or kanban (or bastardised versions of them) means there often isn’t the time and space for writing good docs. Unless it’s very intentionally built into the tasks themselves.
python-requests@reddit
or even the people that are on the call... been told before by someone they prefer to go over something on a call rather than have me write it up, bc its easier for them that way for some reason like how they learn or whatever. fine. then a few days later they wanna meet again to go over stuff because... they forgot most of it...
MoreRopePlease@reddit
Create a story to document something important. A design doc, a user instruction doc, etc. Have a purpose for the doc, too. Most docs I write are for myself, so I have reference material in the future when people ask me questions or if I need to look something up. That's the best way to ensure they stay up to date.
Onboarding docs are updated by the next person to join the team. I jokingly call it the "hazing ritual".
r-nck-51@reddit
Uncommon neurological circumstances aside, we're all capable and we've done this for years in school, and rarely knew how much we really retained from each page.
Then when we read shorter content in our everyday life we assume that the benefit and purpose of reading should be the same whether it's a few lines, a social post or a few chapters.
The product isn't the same, yet we may make a mutually exclusive judgment of them and miss out on official docs and books in favor of texts in the wild and the broken telephone we call AI.
Kapri111@reddit
I will mis this when I finish my Phd, and leave for industry work. I love the academic culture of documenting everything, and being surrounded by people who read with ease.
I've been reminded countless times, by industry folks of how useless this practice is, as it's often labeles as part of the academic uselessness which acomplishes nothing...
jesusrambo@reddit
The shift from doing things because they’re right and interesting to doing things because they generate business value is a big one. Very different priorities
Kapri111@reddit
Yes, but documenting is important. Complex systems become very difficult to maintain over time, if no one takes the time to efficiently document design/development decisions, and if no one has the skill to read those same documents.
SucculentChineseRoo@reddit
There's a reason why loom and other similar services are popular, I make videos because I know people are lazy.
Inside_Dimension5308@reddit
It is pretty common. It is considered boring to read documentation and expects someone to feed them information necessary to do their job.
Changes can only happen if higher management wants to. If they say documentation is mandatory and should be referred to for implementation, that is enough to reduce thse unnecessary meetings.
In my current company, verbal communication is equivalent to no communication. The problem with verbal communication is it cane be twisted later and there is no way to validate what was said. This has lead to tension and chaos in the past.
koskoz@reddit
Please if you find an answer share it with us 🙏
Clitaurius@reddit
This is probably a symptom of information/incorrect-information overload. If you've been around long enough you've probably been burned by incorrect, outdated, or just outright lying (cough cough...Oracle) documentation.
When you join a new team and encounter enough outdated Confluence pages that it is a better bet that the procedure is wrong than right then you start to doubt the whole organization's documentation and wonder if they even have a process. So while YOU might be writing good docs, your coworkers probably aren't and other team members are probably conditioned to just ask rather than read because they have been burned before. Or your docs are only organized from the perspective of the ancients that wrote them (so are everybody else's) and aren't effectively searchable (this is a problem that AI should be able to actually help with).
Maybe it is anecdotal but a few bad apples does spoil the whole confluence.
Huge-Leek844@reddit
I cant even get people to watch 10 minutes videos, let alone reading. Specially, in big companies, people are lazy. Want to learn git? Why reading the doc page when you can pay to an instrutor for 4 hours to read from the doc?
TheSkaterGirl@reddit
Oh yeah I had a few dumbass coworkers like this. I explain something very concisely and clearly in a Teams message, but for some reason they feel the need to get on a call with me to rant. As a very introverted person, this is exhausting and annoying.
Slayergnome@reddit
I think there are some rose colored glasses going on here. Since I have joined the industry people have kidna sucked at reading docs, and things have gotten more complicated.
But also people have (and always had) short attention spans. If you are writing small novels in your explination people won't read them.
Using things like bullets and bolding imprortant relevant stuff helps, but working on getting information across in a succinct way would probably help you out alot.
motorbikler@reddit
Excuse me but we're complaining about the youth of today here
DigmonsDrill@reddit
Too often I'll read the documentation and then find out it's out-of-date.
This doesn't pardon OP's coworkers, since he's telling them where the doc is.
Empanatacion@reddit
This is why "RTFM" raises my hackles. Some asshole who knows the answer and knows they wrote it down somewhere is willfully ignoring that their Key to the Universe is just one book in the Library of Babel we call Confluence.
I read the fucking manual and three others that contradict it, Charles.
ryanheartswingovers@reddit
That’s absolutely the problem. Minimize word count. If it’s faster to show pseudocode for the model, do that not English bullets. Diagram purposefully.
Broad-Emu-7461@reddit
Yeah our job is literally writing in a more concise, precise, and navigable than English. And bro decides to write paragraphs lul
wvenable@reddit
I'm more surprised than not when the documentation is actually correct.
ashvy@reddit
With bullet points, would a question answer format, or like doing the thinking of the people already for them help?
msamprz@reddit
Generally attention spans are and have been "short", sure, but the average attention span has decreased and is getting shorter. (Sorry for not linking to an actual study, I'm not investing a lot of energy in this.)
So while you are right about writing shorter messages, it's also fair to call for a focus back on people's attention spans and try to get them up. Some things really do just require more text.
Working-Truck-8528@reddit
I am of the opinion that a lot of docs SUCK! Big time! Btw. this is the same with a lot of books, posts, written stuff in general...
There is this quote - "I would have written a shorter letter, but did not have the time." Really think if you are talking about the solution, or you are just vomiting implementation details on your audience. Too much details, too fast, is overwhelming and confusing.
Writing is hard and under appreciated. It is an art form. If you cannot find a good audience, maybe you are the problem? Are thinking about the reader?
oldDotredditisbetter@reddit
can someone give a tl;dr of the post
uniquelyavailable@reddit
When I work on a project the first thing I do is briefly read through the entire codebase. Why wouldn't I? I was trained through an older school of thought. I don't care if it's 100k or 1 million lines of code. I read code first, documentation second... it's nice to have the thoughts and context of the people who worked on it while I read the code. I was taught to focus on code first and foremost. Documentation can be unreliable due to human mistranslation and differences in workplace context.
However, it seems the new hires we get can't be bothered to read through the source file they're working on. Modern culture rewards people for thinking about things for 1 second and moving on. I always emphasize to at least read through the connected modules as they attempt to fix code, but inevitably questions will come to me that could have easily been answered by reading first. A tribulation of modern times.
sebf@reddit
You are being “rubber ducked”. It’s not necessarily a bad thing, especially since we have LLM assistants.
I love docs, and wiki at companies. The reason I write wikis is that I have a terrible memory and I hate to search for information many times. Most of the time, when something has been useful once, it will be useful a second time, even if it’s for another person.
I get what you feel about “meetings”: they are sometimes a loss of time, especially because after a meeting, there is nothing left (except maybe relationship, but I am not sure there’s a real difference in relationship making compared to chat).
Sea-Flow-3437@reddit
Are the documents concise? Or do they waffle?
LostWeb-17@reddit
I live on them and oddly only comfortably understand something after obsessively reading the docs over and over again until I know something. It bothers me not knowing something well enough to utilize it in the middle of the woods with no network connection. Like yew for example. I really like yew and like reading the docs for it.
tjeeraph@reddit
I once heard the story, not sure if true, but at Amazon meeting attendee gets a 2-5 letter memo of the topic. So each member gets informed and they can then discuss with the same knowledge. Probably you just have to force it?
Also, the same story told, if it’s not important enough to write down, it’s not important enough to discuss anyway
rochakgupta@reddit
Yeah, I am dealing with this at work a bit, especially with new grads. Loop of: "get the error -> feed it into GenAI tool -> get possible steps to fix -> try -> repeat" has taken away the need for people to actually read what the error is and root cause it. For anything non trivial related to security, operating systems, networking, etc, it is expected to understand how things work under the hood which in turn requires dedicating time to read existing documentation (not the summary extracted via GenAI; it defeats the purpose). I guess we'll see long term implications of this in a few years. I've got my popcorn ready.
Herrowgayboi@reddit
Amazon would love you. 😂
herbicidal100@reddit
TLDR
herbicidal100@reddit
TLDR
severoon@reddit
Yes to not capable of reading, no to "no longer." This is how it's always been.
Bezos talks about how he ran technical meetings at Amazon. He would force the meeting organizer who wanted a technical decision to create a short memo. (I think it was one, or maybe three pages max?) Then the first 10‒15 minutes of the meeting was set aside for everyone to sit around a conference room table with a printed copy of the memo and no devices and physically and carefully read it.
I know, it sounds like kindergarten. And now it's one of the few $1T companies. Because people will not read.
Notice there are several steps here. First, he had to force people to write what they wanted to say in a concise memo that communicated only a base set of knowledge required to have the specific discussion. Note: People pushing for a decision should be forced to record in print what they are asking for and why anyway.
You don't have to include everything, that can be introduced in dialog, but you do have to start everyone from the same place assuming they know nothing about the specifics of the discussion. This step alone forces the meeting organizer to clarify their thoughts. Note: This is something everyone should be doing when they write tech or decision docs anyway.
Attaching the document to the meeting invite guarantees many people won't read it, so the first part of the meeting is dedicated to actually reading it. This means you can just show up, no pressure to do pre-work. Note: You should be able to expect responsible people to do some pre-work (unless you have a track record of wasting everyone's time).
This worked at Amazon because it was the big boss man himself insisting on it, and participating in it. It won't work if you try to graft it into company cultures where there is no strong authority figure people are trying to impress with their obedience.
Even if you diligently do the work yourself, if you go around acting like this is table stakes (it is), you will immediately alienate your coworkers. If someone says something and you point them to a source they were supposed to read and gently let them know what they've said is already addressed, even in cases where they could plausibly have read it and it slipped their mind, they will respond defensively because you are pointing out that they didn't do the work they want everyone in the room to think they did. You may expect everyone else in the room to be on your side, but that is naive. The majority of people in the room is equally insecure, and they'll line up against you as a pedant, superior, know-it-all who's not a team player, and you're being political by trying to make others look bad. (This is every company I've ever been at except one.)
Basically, it's high school. Most people, most of the time, are not focused on problem solving, they're focused on presenting the appearance of problem solving. If these two activities conflict, appearance always wins. As an actual problem solver, your job is to strategically align the two. You can get a long way in this direction simply by literally telling the person publicly that you can see they did the things they want everyone in the room to think they did before correcting them.
Here's what this looks like. Your doc says, "Of course we should never even think about doing X, because X is stupid." You go into a meeting and before you get to that part, someone pipes up and goes, "Obviously we should do X!" The way you are currently working, you'd respond, "After the intro, the first heading in my document in 36 point type says 'Why X is stupid'."
Instead, you should say, "That is actually very insightful, in fact you and I are thinking exactly along the same direction!" Now from here you have a choice, you can do the soft switch or the hard pivot:
You might think you can't get away with just ignoring what someone says and pretending they said the opposite, but if you can quickly clarify a much better alternative and make it seem like that's where they were headed, most people will immediately jump on board. Truthfully, they don't really care about the thing, they just want to be seen as contributing, so pat them on the head and thank them, and keep going. Most people after the meeting will not even be aware of what happened even though it's obvious. (You have to be really good to get away with this in a recorded meeting, though.)
I'm being a bit silly here to make the point, but in truth, this is just how it's always been. The docs you write are not intended to be read, they are a record of your work, they are a durable work product that associates your name with work you did at perf time. That's it. All of the actual information is not going to escape the doc once you've hermetically sealed it into that perf time capsule by writing it down, you need to market it in other ways.
Somewhat cynically, at most companies an approach that works is to get your idea written down, get a few people to review it and start circulating it around, and then when you market it (not in print), attribute the key parts of your idea to a politically powerful figure in the company. You can say things like, "Of course I think the best technical solution is to do X, but so-and-so is hyper fixated on Y, so I had to build it around this." So-and-so will be just as surprised as anyone else when it eventually gets back to them about the idea they had, but as long as it was something "you heard," the rumor can't be attributed to you. Besides, if it's a good idea, so-and-so will definitely take credit for it anyway. Just make sure to only do this for things they don't really care about, don't try to contradict something they actually are focused on.
constant_flux@reddit
Honestly, I think your post illustrates the problem. It was way too long, so I had ChatGPT summarize it in a manner that I could digest quickly. Why should I read more than necessary?
Jeff Bezos instituted a process at Amazon requiring technical meeting organizers to write clear, concise memos that everyone would read together at the start of meetings—because people won’t read beforehand. This forced clarity of thought and created a shared knowledge baseline. However, in most companies, this culture doesn’t take root unless enforced by leadership.
In reality, many professionals are more concerned with appearing competent than actually solving problems. If you point out that someone didn’t read or misunderstood a document, they'll get defensive. To survive in such environments, the author suggests using political finesse: pretend colleagues' bad ideas are insightful, subtly steer the conversation, and attribute your good ideas to influential figures to gain traction.
Ultimately, technical documents serve more as performance artifacts than communication tools. To have impact, you must “market” your ideas socially, not just write them clearly.
severoon@reddit
You're right. Instead of watching movies or reading fiction, just let ChatGPT tell you the gist. Same thing, really.
It's a complete waste of time, but you can confirm for yourself by reading what I actually wrote, and then verify that, yup, you got the exact same information.
constant_flux@reddit
That's a false equivalence. You read technical documentation and watch movies/read books for completely different reasons. Your comparison would hold if, for example, your teacher/professor is wasting your time with bloated assignments. Which, for me, was routine throughout my educational career.
severoon@reddit
Did you read what I wrote above and compare it to ChatGPT's summary?
constant_flux@reddit
No.
severoon@reddit
My point is thus made.
If you did the homework, I believe you would immediately grasp precisely how you shorted yourself here. lol
constant_flux@reddit
No, I understood your sarcasm. You didn't understand mine.
pedroren@reddit
Mind that a lot of people prefer verbal communication to written, especially managers. Not even willing to read 3 lines in an email, they'll always want a meeting.
cosmicloafer@reddit
There are stupid people everywhere, try to avoid them if you can!
besseddrest@reddit
Just because something is documented doesn't necessarily mean the dots will automatically connect. The reader may also have questions that feel unanswered because maybe it's pertaining to something specific about their use case.
Despite this, when questions are asked sometimes it gives the impression that the person didn't read the docs. I think that just comes down to - the person asking needs to put better effort in their question & the person answering should give them benefit of the doubt
But yeah if they didn't read that's on the asker.
You say that you end up repeating whats in the docs, maybe it doesn't quite click and they need it rephrased. I'm like that.
When I offer to help others one thing I try to identify in conversation w/ someone is why they aren't understanding the concept, maybe there's some deeper fundamental knowledge they misunderstand, maybe they learn a specific way. I can't assume that someone is going to read something I wrote and fully understand what to do, maybe this person needs me to show them. I think the extra effort in understanding who you are talking to and how they learn helps the 'team' aspect of the job
IMovedYourCheese@reddit
Turn the doc into a series of Instagram shorts and you'll have more luck.
zdwolfe@reddit
Yes, people have given up reading
zhivago@reddit
The most important parts of a dd are Goals and Background.
Align stakeholder on these and get them to sign off.
To solve your meeting problem ask for people to review and comment in advance.
Then make the meeting agenda to discuss open comments only.
Use the document for this meeting's agenda/notes.
Have a single design proposal followed by several alternative designs.
Capture all of the stupid ideas in the alternative design proposals where you explain why these great ideas won't work.
Good luck.
PM_40@reddit
Social Media fucked the attention span and ChatGPT will fuck writing skills. A high school teacher quit crying because kids cannot read and write and submit assignments using AI.
tn3tnba@reddit
People can’t even finish a slack message
taznado@reddit
Only open source projects support that.
CricketMysterious64@reddit
Depends on how much jargon you stuff into the doc without any explanation. If I have to google half the terms I’d rather just ask.
weightedpullups@reddit
Have definitely noticed this, it’s not isolated to engineering though. In general I find that most people don’t want to read much of anything, let alone a long technical document that requires some brain power to understand well.
Have not found a solution to it, beyond just repeating things again verbally. Problem with that is unless it’s a very long discussion, important details or ideas may be missed anyway.
yellowmonkeyzx93@reddit
This especially.
freeformz@reddit
This basically explains a lot of the dysfunction in at least America ATM.
fireflash38@reddit
AI to make things longer. Then AI to shorten it down so people read it again.
MrMichaelJames@reddit
People right out of college or out over the last few years? Yeah it’s a problem. A lot of them can’t even sit long enough to read a few pages of a book anymore. Mobile devices and social media have destroyed the attention span of 20 year olds and younger.
vulpine-archer@reddit
Tldr
robberviet@reddit
Personally, I blame tiktok and youtube to lesser extent. 30s videos are garbage, but why do you feel the need to watch a 1 hour video, when content can be summarized into an article? I can easily skip parts I knew, copy paste code/commands/config easily too.
Most people when I asked why they don't just need read novels/mangacinstead of tv series adaptation when 99% of the time it sucks: watching is faster. Like how? Have they never read before? It's just laziness.
I know something are easier to understand in visualizations, images.
A4_Ts@reddit
Some docs are god fucking awful(I’m looking at you Android Studio) and some are great. Me personally i try to look for a simple “hello world” example and go from there. All devs have had horrible experiences with bad documentation and a lot of them read it as a last resort, they’d rather go ask AI or go on stack overflow first
hazily@reddit
AI and vibe coders.
Impossible_Ad_3146@reddit
Yes this post be too long
Im_not_the_cops@reddit
@grok can you summarize this?
Northbank75@reddit
So I realized sometime ago that my documentation didn’t work for the less technical and non-developer roles in my company. I heard a story about school teachers in multinational schools using AI to ‘level’ the language use so account for people who may not have a firm grasp of English … long story short, my latest report to the execs was plugged in and summarized really really nicely and accurately … and they engaged with it…
ChatGPT
mechkbfan@reddit
It might be worth reassessing how you structure your documentation
I'm someone that loves documentation, but when I see a comprehensively documented page, my usual thought processIs "How much of this is actually relevant? What is that referring to? This isn't answering the question I had. I'm lost already".
So I have different pages for different goals
If I had to structure my top three
High level architecture might just be how each solution goes together. Or it might be the internal design of a solution
FAQ is usually just simple 1 liners that help explain a concept for context of business Maybe it seems obvious to you, but I usually write them for a new starter
Common problems & solutions There's always some random thing occuring, like "xxx key is no longer valid" As a user, I don't need an essay on the architecture, just give me the damn link and how to get permissions to rotate it
If people have problems, the majority of the time these pages have solved it for me. If it doesn't, I ask them specifically to list what on the page was confusing, missing, etc.
Intelligent-Ad-1424@reddit
People often aren’t given enough time for stuff like that anymore. Sprint culture made sure of that.
BertRenolds@reddit
A lot of it is just dated or I am asking one specific thing that the doc doesn't answer. I actually hate being sent long useless documentation as if that's helpful.
For design docs, I say at the beginning of the meeting, everyone read it and we will discuss in ten or so
nasanu@reddit
Personally I find.. well just about everything written by a developer incoherent nonsense.
Most recently I needed to know where/how I was getting one variable Asked the API Devs and they say it's in their docs, I say no your docs are useless. They point out a diagram in the docs that has an arrow with the variable name coming firm a box...
I asked how do think that is helping? They say all the info is there... To be clear that is all the info to work on, a box and an arrow. What is the box? Don't know. What request to send to the mystery box? Don't know. What it will respond with? Don't know.
Specific_Ocelot_4132@reddit
I had one colleague in particular who refused to read anything and it was so annoying. Every time he had a question for me he wanted to do a zoom call.
bloudraak@reddit
It comes down to “human factors”.
I frequently distrust lengthy documentation, which is often not maintained. So many documents suffer from verbal diarrhea. To make matters worse, the overall content lacks “architecture” and “flow;” it’s too “dense.”
If you want folks to read documents, write documents that are worthy of reading. Don’t assume that just because you wrote them, they want to read them or will prioritize them.
For meetings about documentation, allow the first 15-30 minutes to read the document before discussing it; avoid simply repeating what's written to keep engagement.
Human factors
roynoise@reddit
I had several meetings with one guy about the use of a very run of the mill web app. Meetings, phone calls, emails. I wrote him multiple explanations, recorded multiple videos. "Click this button to do this thing." Still, he demanded more attention. When I made a boundary, he went over my head to create administrative troubles for my whole team.
Sometimes the customer is not only wrong, but an absolute ingrate.
Repulsive_Constant90@reddit
An ability to understand and analysed complex technical topics is a skills. Not every dev equipped with that skill. It takes not only dedication but the right mindset to do so. This is a very common issue. I can tell straightaway if that dev got this kind of skill or not from how they talk about technical stuff. Unfortunately, this kind of skill is not easy to spot during an interview. That’s why we flooded with unqualified dev in the team. Because this is not a technical skill rather ability and/or willingness to dive deep into a topic/problems.
WarAmongTheStars@reddit
Capable? Yes.
Willing? Damn near 0 unless I'm being paid.
No_Imagination_4907@reddit
I've been fighting this battle for a few years now. I think younger people nowadays don't want to read. At my company if I want to teach them something, I have to either set up a workshop providing hands on practice, or find video materials. Most younger devs just refuse to learn by reading docs and tinkering. They want knowledge, but it must be quick, and served on a silver platter.
Pale_Will_5239@reddit
Social media has shortened in memory comprehension.
Technical_Gap7316@reddit
Were they ever capable? Many people are just lazy or frankly just dumb. Engineers included
I have learned to accept it. I still write long, detailed explanations once in a while, but often, I will simply not respond to dumb questions.
If you make people wait, they might actually put some effort into answering it themselves.
Currently, they're treating you like they treat chatgpt. Dont indulge them.
xdevnullx@reddit
I once heard that by giving brief answers, you force someone else to go exploring.
Honestly, I still struggle with thinking I’m not being a “team player” because I point to documentation instead of answering myself.
earlgreyyuzu@reddit (OP)
wait, I got that exact feedback. Apparently, I'm not sharing info or explaining things if I just point out where the answer is in a doc or past message. How does that even make sense?
Technical_Gap7316@reddit
If people got used to you being a pushover, they will get mad when you stand up for yourself. It's super important to set boundaries early on.
It's honestly one of the biggest life lessons, and I'm only learning it now in middle-age.
xdevnullx@reddit
Is it the delivery?
Like do we need to soften the tone by saying something lIke "Hm, I found by looking through slack and confluence, could you take a look?"
Idk, I suck at speaking corporate. I've been on a path to avoid management since I had an early experience in my mid 20s (mid 40s now).
Technical_Gap7316@reddit
Delivery matters, for sure, but in my experience, the most successful people don't actually speak in the corporate tone. Instead, they're direct and consistent.
drumDev29@reddit
I think it'd be fair to respond "I'm not your personal chatgpt, go look in the docs."
aseradyn@reddit
If it's a question that I know they could answer if they did when a little review of docs or our past chat history, I don't answer for at least 20 minutes. Usually by then I don't have to
earlgreyyuzu@reddit (OP)
"they're treating you like they treat chatgpt"... I've had that thought more than once while writing answers to their questions
angrynoah@reddit
We should replace leetcode with reading comprehension tests.
mixedCase_@reddit
I have not noticed a difference. People never read stuff unless it's of extreme concern to them and are able to realize that it is of their concern. The easiest differentiator for a dev has been "actually dares to open, read and comprehend anything written down about a tool, specially official docs" for as long as I can remember.
nemec@reddit
Come work for the Rainforest (lol)
I didn't understand before, but now I get it: people often just aren't going to read your doc if you don't block time on their calendar to devote to reading it.
Before discussing it, have them spend the first 20-30 minutes of the meeting reading it. Even better if you're using a doc product with inline comments so people can leave questions and you can answer them live while everyone is reading.
This also helps if you have the ability to permalink specific paragraphs so you can send a link to the paragraph and say "here you go"
Axamanss@reddit
We’re literally bombarded by information in our daily lives now. Documentation is great for perpetuity so that in a year people understand what choices and why they were made.
But for implementation? Bullet points my friend, thin slice, write Acceptance Criteria.
Xsiah@reddit
Docs and long text are different things IMO - If you have a well thought out, structured doc that's easy to read, sure, no problem. But I'm not going to read some dev or PO's manifesto that made sense to them when they brain dumped it into a document. Writing good docs is a skill that not everyone has, and it's not necessarily the recipient's fault if they aren't about to read it.
JaneGoodallVS@reddit
One of the turbo-billionaires (Gates?) gives people some time at the beginning of the meeting to read docs. He reads it with them.
Broad-Emu-7461@reddit
Yes if you write long-ass paragraphs like that, put it in bullet points
Natural language has way too much meaningless bloat
Why would I read your paragraphs when I can read code?
But I also watch youtube at 2x so ymmv
CraftySeer@reddit
I had to write “My apologies you had to repeat yourself” just twenty minutes ago. I try. I fail. I try again.
omz13@reddit
In a similar scenario, somebody one said "how many times do I have to explain this to you" when a colleague asked for the same thing for the third time.
abeuscher@reddit
The degree to which people will read what you write is inversely proportional to their position on the org chart in relationship to your own. That is not right and it is not productive but it is true.
earlgreyyuzu@reddit (OP)
Hmm that's valuable insight. I think that is generally true... however, in most cases these days, I don't write messages or docs unprompted. They either asked me questions or expected me to write a design doc after asking me to lead a project.
abeuscher@reddit
I don't think that people ask for reports or documents because they want to read them. And I don't think they usually do once they get them. You're being tasked with writing a large doc that probably makes it into a bullet point in a presentation up the chain in the best case scenario.
The number of times I have seen members of the C Suite or really any management react to anything but decks is 0. And I have been in it for 25 years. The things people say != the things people do.
I'm a bit cynical, though. It could be that there is a functioning software company that delivers a necessary product run by people who are not sociopaths. I have yet to find it but I believe in it. Sort of a bureaucratic agnosticism.
omz13@reddit
I used to work at one place that was engineering lead. It was great. Over the past 20 years they've been going through RIFs and retirements and it's just not the same... they're getting more social and less engineering focused because gotta raise awareness whereas in the past there was no need because their engineering chops drove their reputation.
DoingItForEli@reddit
@grok what is this person saying?
Caramel-Bright@reddit
People have been this way for at least the last 10 years I've been working though I would definitely believe they've gotten worse
floobie@reddit
The charitable explanation: people learn and ingest information differently.
I’ve been simultaneously praised and criticized for writing detailed analysis notes on investigation tickets.
Some people just do better with a high-level skim and then talking through the details, some can’t catch all the details verbally (me).
I just try to write my documentation in a manner that’s easy to skim, but has enough detail for those who can handle it in that format.
PayLegitimate7167@reddit
Yeah I get it I think the cognitive load has increased in SE and probably too busy doing coding that they don't want to break their time to look at documentation.
omz13@reddit
And, if they bothered to read the documentation, probably quite a bit of that busy work could have been done in an easier way.
In a former life I was a tech author and it was depressing how much time (and money) was spent writing documentation and nobody bothered to read it (except the lawyers or auditors when things went too wrong)
CodeNiro@reddit
Just had a devops guy get angry when challenged about design decisions that weren't covered in a 16min Youtube video. The video was about a guy vibe coding :/
JamesLeeNZ@reddit
The code is the only sort of documentation I have ever read
OkMacaron493@reddit
Management wants our RnD org to AI everything. I’ll read internal docs but for external info use AI as the starting point and only dig deeper if I need further clarification.
People in general will not add documentation or read it unless forced to do so through office culture.
SomeEffective8139@reddit
I find that the reading comprehension level of people is falling gradually, and especially (but not exclusively) younger people have terrible ability to process a block of text and understand it. I think developers tend to be pretty good at reading and understanding code but for some reason there is often a disconnect when it comes to written communication.
bluenautilus2@reddit
No. No one can read. Especially the people who come in asking for everything to be written down for them before they even start. Those people can't read the most
shozzlez@reddit
The first meeting is usually just to read the doc that people should have read already.
StillEngineering1945@reddit
It was always like that.
bonisaur@reddit
Those people will not do well in high risk, high impact products or services. I can't imagine you can make a mistake more than once in say a medical device company for the reasons you stated. If this is the type of environment you'd want to work at, you'll probably want to look into automative, embedded, medical device, or military roles.
However, people with good intuition and ability to summarize while maintain some reading comprehension of what they skimmed will do well in a faster pace, low risk environment.
bentreflection@reddit
You’re falling into the classic trap of thinking other people should pay attention to the things you think they should pay attention to. Just like every person who fires off an email to you thinks you should drop everything you’re doing and get back to them because their email is important.
People are super busy and in today’s world of endless notifications and information overload people manage their time and schedule by reducing incoming information down to what is immediately necessary and ignoring everything else.
If you give someone a lot of text they aren’t going to just trust that everything in it is super valuable and worth the time to actively study they are going to skim it hunting for specific bits of information that they think is important.
People are like chickens hunting the ground for kernels of information to peck at rather than baby chicks waiting in the nest for you to drop a worm of knowledge in their open mouths.
constant_flux@reddit
💯
sarhoshamiral@reddit
Welcome to the world created by Slack, TikTok. I agree people really don't bother to read anymore.
opideron@reddit
In my experience, a lot of these documents tend to be unreadable, offering tons of technical detail when you just need to know how things work at a summary level. Still others are out of date. Scratch that, most of the documentation is out of date, and reverse engineering is almost always necessary.
Writing readable documents is a talent most engineers don't have. Keeping documentation up to date is typically relegated to the lowest priority.
While some of your experience might be attributable to people not wanting to read, I suspect that isn't the problem, in part because I'm an avid reader and my eyes glaze over when trying to read most technical documentation. I've found that the best approach is to explain things in person (in a meeting, etc.) and answer the questions that come up. Those questions will help fill out all the missing information in the main document. Then going forward you can refer your team to the document, and to come to you with questions should anything in the document be unclear.
I note you complain about your team interrupting and going on tangents. There's typically a reason for that. One possibility is that they lack focus, for which I use my rhetorical question "What problem are we trying to solve," which is a polite way of getting the meeting back on track. The other possibility is that your presentation skills might need improvement. Typically when I give a presentation, I'll use the document (usually slides) to remind me of the topic, but I'm also interleaving the topic of that slide with the overall context of the problem. They listen to me in large part because I'm saying things NOT on the slide. If you're just reading your documentation in a monotone, for example, of course attention will wander.
Either way, it's not easy, mostly because technical topics can be extremely dull, and you typically need a hook to make people interested. My hook is typically, "Here's the problem, and this is my proposed solution. Please point out anything that I might have missed." So I'm not lecturing students so much as asking respected colleagues for advice. But even then, people's eyes will glaze over. But it's not because they don't want to read, it's because the topic is dull and reading is typically unrewarding for them.
constant_flux@reddit
Beautifully put. 100% agree.
Toohotz@reddit
I feel like we work at the same company 🙂
lWinkk@reddit
Yep. Same shit. Write extensive docs on everything I know, then I’m forced to do a presentation KT session where I literally just read the docs and perform the steps as already listed in the FUCKING DOCS. No one reads them beforehand. No one asks questions before/after then I am getting daily message of people asking if I can do quick calls where they ask me a question that is answered in the FUCKING DOCS
constant_flux@reddit
I'm going to have an unpopular opinion: I find sifting through docs to be largely a waste of time, especially when specific functionality is buried in the docs like a needle in a haystack. Additionally, you may need functionality from one domain that you have to pipe into another. This means reading multiple docs.
What's better, you might ask? Examples. Lots of examples. Show me how to do common tasks, and THEN I can read the documentation to hone my skills. Nowadays, I have AI read the docs for me and build whatever it is I need based on that. But before AI, it was StackOverflow and Google.
I hear the RTFM crowd, but there's a reason why questions are commonly crowdsourced. And while I sympathize with the arguments that not reading the docs is lazy, I'd argue that telling people to RTFM is also lazy and defensive. A lot of documentation is shit. Pure, utter shit—for many reasons.
And let's not forget that sometimes you have to RTFM only to find out it's not in the docs. You tell the maintainer, they get defensive and smug, and finally, they admit their docs need improving.
So, bottom line? It's a gray area. Some docs are easier to read, follow, and have more relevant examples than others. The shittier the docs are, the more likely I am to ask for help.
internetroamer@reddit
Words hard
MonochromeDinosaur@reddit
GPT and short form social media/videos wrecked people’s ability to pay attention for long periods of time.
It’s a skill that takes practice, before it was all we had. It’s similar to how TV wrecked a lot of people’s patience for reading books.
Paying attention takes practice
Complete-Equipment90@reddit
Come on. This is frustrating to not be heard. I get that. But, in general? Long docs are a thing of the past. They get outdated. They aren’t easily or equally understood. Many people would rather just get their hands on an example.
Presenting a design doc is the current way every team does this.
Im sorry that you’re frustrated.
crystalpeaks25@reddit
yes i keep seeing people in tech glossing over or just looking for keywords in a technical document.
you always get, oh! the dov said dont use this feature so we shouldnt but when you actually validate it says sure dont use this feature solely to do X, you need to use X eith Y to achieve Z.
Omegatard@reddit
Tldr?
NobodysFavorite@reddit
Hey chatgpt, summarise the post that OP has just made into a one line TL;DR.
Technical-Row8333@reddit
well, I'll copy paste your document to my coding agent if that helps.
paulwillyjean@reddit
I still get flashbacks whenever someone asks me if I’m free to jump on a quick call to review everything. I think there’s a universal rule those meetings always have to happen when you’re neck deep in code trying to figure out some super weird bug.
Solome6@reddit
At Amazon he culture is to read the doc that we will be discussing during the meeting that way everyone has time set aside to focus on just that. After everyone reads for like 15-20 min then everyone discusses together.
Du_ds@reddit
I didn’t even read your post. Too long didn’t read
TL-PuLSe@reddit
We leave time at the start of doc review meetings for everyone to read the doc. That way, nobody needs to find time to read things before the review, nobody is bullshitting having read it, etc.
CptDonki@reddit
Not only docs, I see same thing for long emails too. So discussion go to chat instead of full context conversation in email...
jellybon@reddit
I'd rather have emails over scattered messages on Teams or worst of all, long ass phone calls where people keep either talking in circles or wandering off topic and bringing up things that are out of scope.
Zealousideal-Ship215@reddit
Been trying to solve this problem for many years lol. I generally try to keep written documents as short as possible but that still doesn't work.
If you give people a list of 3 or more steps that they need to do, then a blindness comes over them where they will completely skip some steps. But they will still tell you that they did every step.
Right now LLM AI is a hot topic, but one good thing about AI- it actually reads everything you write.
ocxricci@reddit
TLDR.: yes
agumonkey@reddit
Mostly agree, but there's a lot of doc that also don't "culture fit" my brain. I want concise, mechanical informations about the programming context i'm in, not a fluffy story about how great is. I almost miss UML diagrams these days.
sysera@reddit
This has been a thing for the last 20 years. It's not new, but it has become more blatant.
daedalus_structure@reddit
No longer?
I've been trying to get people to read a freaking stack trace for the last two decades of my life.
HoratioWobble@reddit
Without fail, every time I've worked somewhere, the docs are badly written and often out of date.
i spend more than trying to work something out because of inaccuracies than I do if I just ask someone.
They're usually encyclopedias themselves, literally no idea where to start.
And I'm sorry but most engineers are just not good writers, which is important if you want someone to read, comprehend and digest.
I've found the better approach is to document everything in code either through the code itself in the form of good naming, consistent structure and types. Through tests, codified contracts and automation scripts
hazelholocene@reddit
I just created a Rag that gets gpt4 to answer it for them 😊
Hot-Profession4091@reddit
Fam, they don’t seem capable of reading a flowchart or state diagram.
TallGreenhouseGuy@reddit
Like Joel Spolsky said in his little essay:
”When you design user interfaces, it’s a good idea to keep two principles in mind:
Users don’t have the manual, and if they did, they wouldn’t read it. In fact, users can’t read anything, and if they could, they wouldn’t want to.”
I have found throughout my career that this seem to apply to all written material…
https://www.joelonsoftware.com/2000/04/26/designing-for-people-who-have-better-things-to-do-with-their-lives/
Fluid_Economics@reddit
Docs can be out of date or irrelevant. I've read stuff for hours only for people to tell me it's all gone. Wtf
ILikeBubblyWater@reddit
I learned that 90% of whatever people want me to read is completely useless to the tasks I have to do, so I stopped reading stuff and ask if I actually need information or I dump it into an AI and ask that.
I have a colleague like you, writes ADRs and long Readmes and everything that no one ever uses or needs.
I need straight up answers not a novel, if you want colleagues that value reading join a book club.
alex88-@reddit
I don’t think it’s as much laziness/attention issues as it is a need/a company’s need for efficiency.
It’s like asking for someone to read an encyclopedia back when the internet/search came out - it’s ultimately a waste of time for the context you’re working in. Same thing with LLM usage now.
I agree 100% that a design doc written by your teammate and relevant to what you’re working on should be read fully. At the same time, I can see why some people would just prefer to ask targeted questions if the scope or their work is small and your design doc is v large.
If the info they want is in your doc, then just link the doc again when they ask instead of wasting your time.
gibbocool@reddit
Yes. Anything more than a paragraph and nobody reads it.
Four hours struggling and debugging saves 5 minutes of reading documentation after all.
The most annoying thing is when your manager asks a question that is explicitly answered in a document, you link them to it, and they set up a call as they couldn't be arsed reading it. And then once they see how easily they could have just read it, they excuse themselves saying they didn't know that process. Well mate. I'm linking you to the process. Read it.
higherpublic@reddit
Yeah, most people are no longer capable of it anymore.
It's a mix of low attention span/focus/executive function (TikTok or just health issues, etc), just trying to do the minimum, lack of literacy, a preference for "learning by doing", demoralization, maybe more.
I'd recommend a multi pronged approach: 1. Meet people where they are: whatever you wrote, it's still way too much. Cut. 2. Drag people to where you need them to be: start every meeting reading the damn thing together 3. Else let people fall through the cracks in a way where they get in trouble but the project isn't put at risk. People need to be stimulated into adapting out of this crap.
RusticBucket2@reddit
Man, I’m not reading all that.
Vunderfulz@reddit
Amazon does almost everything wrong, but one thing they do right is document reviews. It's assumed that nobody has read the doc and everyone reads and comments in silence for the first half of the meeting.
Obvious-Sarcasm@reddit
I've had the same experience. I introduced an architectural change to make all platforms working on projects more flexible to changes.
Wrote an architectural doc that explained everything with design patterns, class diagrams, and sequence diagrams. Some devs on some platforms picked it up quickly while other devs seemed to not understand the concept at all.
Using well established design patterns as the main driver of the architecture, they were confused as to how to even start development. Making suggestions to modify the architecture that didn't make sense or had any thought put into them.
It's definitely frustrating, but what got me through it is understanding not everyone thinks like me. Some people will understand how to implement things just by hearing the idea, some people will need step by step instructions just to get started.
texruska@reddit
On the flip side, a lot of people suck and communicating technical concepts in a way that is appropriate for the target audience
It’s easier to hop on a call, where if I’m missing some context or knowledge I can ask
I also like to write docs, but I’ll then do a call as a primer. I’ll give the high level details and then give them the doc to fill in specifics
When reading technical docs without a primer beforehand my biggest question is usually always “so what?”, which is the first question that should be answered
afty698@reddit
At my current company it’s not uncommon to take the first 10 minutes of a meeting to read the doc. It’s just acknowledging that no one reads these things on their own, but it's effective.
DigmonsDrill@reddit
It's bad but it's better than trying to force people to do homework before the meeting. I shiver when I think of what people would force me to read for a meeting I don't even want to be in.
isurujn@reddit
If you feel like you're being "forced" to read, that's a you problem. But the reason for providing any material prior to a meeting is so that you can read them and note down any questions you may have so the meeting can be actually productive. Otherwise you'll likely need another follow-up meeting to dicuss the things you thought of later after the first one.
hostilereplicator@reddit
I am convinced this is the best way to do things having experienced it at Amazon and now introduced the practice to my new place.
Amazon also benefits from getting people to do writing training, and cultivating a writing and reviewing culture, so the documents tend to be reasonably well written.
Didn’t like much else about the place, but that was pretty good.
syklemil@reddit
They never were. It's been a long-standing tactic in customer communication to only send one question, because only the first one will be answered.
The tangents are probably important to them. Having people interrupt, especially with questions, should hopefully be an indicator that they're paying attention. Part of being young and inexperienced is just that—they don't have the experience to tell them what's important and what's not.
It might also be that you're just overwhelming them, ref that XKCD about field experts vastly overestimating how much others know.
Fuck me if I know. A library? The EU bureaucracy?
freeformz@reddit
Similar/tangential to large PRs just getting a “+1”, while small PRs are nit picked to death.
DavidChenware@reddit
Just throwing it out there that there is a possibility you aren't great at written communication and technical writing.
dnult@reddit
There is an art to writing good technical documentation, and one of the best approaches is to give the answer in the first paragraph and then explain the why. Some people write like they think and lose their audience in blah blah blah.
Life_Equivalent1388@reddit
Its easy to read big documents. You just give them to chatgpt to summarize.
You can make an automation workflow that can turn it into a series of TikTok videos with some endless runner game footage playing in the bottom.
kasakka1@reddit
I'd have to see what your documentation looks like to make any educated guesses.
I like to skim through documentation where I find the important bits and ignore everything else. While this occasionally bites me in the ass by missing some important detail, most of the time it works.
So I try to write documentation with the idea of communicating things easily to someone else who skims.
To me what works is using plenty of bullet points, headings, diagrams and avoiding long paragraphs. Enough variation to keep the reader interested without overwhelming them with too much info at once.
benabus@reddit
Some people don't comprehend things well through reading long documentation or have attention disorders. Granted, the people you're talking about uprobably are not these people.
I hate reading as long as I can remember and reading 90% of papers and documentation will literally cause me to fall asleep at my desk regardless of how hard I try or how much caffeine I've had. That being said, I love me some good documentation. I'm not going to go cover to cover, though.
I had a non-techy explain that they don't like how a lot of technical people write because we don't write for an audience, we just kind of write how we would talk. Having a design doc with an outline and a toc or something where I can look up the information I want is much different than a 2 page email that requires me to read the whole thing to understand any of it. I have other work to do, there's no reason to write moby dick in order to tell me about a new TPS cover sheet.
When you have everything written down somewhere and someone asks you a question, you can always try pointing them to the specific part of the document and asking if they understood it. It's possible that it's just your document that's the problem and no one wants to read it. Kind of like how I'm sure most people won't want to read this whole post of rambling nonsense.
richsonreddit@reddit
I’ll read 3 bullet points, max
MoreRopePlease@reddit
I send a link to my doc in response, and then maybe follow up later to see if they have additional questions.
After several repetitions they learn to bookmark my doc and check there first. It's still not foolproof, so I will sometimes give the answer and include a link to the doc.
WiseHalmon@reddit
I'd use ChatGPT to create a custom GPT that only responds with excerpts from your doc, lol.
but to answer your question... maybe government or military or highly scientific work
janyk@reddit
Government? Here in Canada, government IT is known for being less competent
WiseHalmon@reddit
My point was these people spend more time reading and nit picking or reviewing standards than most people. OP mostly asked for people who read not competency 😅
WiseHalmon@reddit
oh, oh, and safety critical stuff
Exact-Guidance-3051@reddit
I have very short memory and i need a proof so I take a meeting but request everything to email. If it's something more complex, I write meeting minutes and structure all knowledge in word document or shared google doc for more contributors.
Good maintained document can lead a team on it's own.
Erutor@reddit
Tl;dr
;)
eightnotes5@reddit
Not only that, they can’t seem to write coherently either. Even with the help of AI. It’s maddening.
jepperepper@reddit
i see this constantly - project lead keeps having this conversation: "oh, i thought PO and i had agreed that would be cornflower blue, i'll talk to him about why he wants it green now" and then 2 weeks later "oh, i thought PO and i had agreed that would be green, i'll talk to him about why he wants it cornflower blue now" ad infinitum.
no docs.
lead's boss agrees - do not do "comprehensive documentation" which apparently includes a basic set of user stories or even a user manual for the UI.
i really don't know what to do with these people.
wwww4all@reddit
Why are you writing docs instead of actually building things?
Actually build things and show the nuances in projects.
tilapiaco@reddit
The best way to politely tell people to read the fucking docs is to emphasize how much time and care you put into making sure everything they need to know is in there, and please come to the meeting having read them, etc
foxyankeecharlie@reddit
I seriously thought about making TikTok style videos for internal trainings. So people who can't or don't want to read can watch the short videos instead of pinging me and ask questions clearly answered in the doc with big ⚠️ emoji.
SynthRogue@reddit
Honestly, nowadays I'd give the doc to AI and ask it to give me answers to my questions based on those docs. Faster than reading the whole thing. Because sometimes you can read a section but are unaware of some particular thjng that's located in another section.
Internal_Research_72@reddit
Internal docs? Things are outdated before they’re even finalized and shared. If you want to know how it works, you have to read the code and reverse engineer it. That has conditioned me to just ignore your doc. Even if you personally have done a good job at keeping it current, I don’t know that.
Phunk3d@reddit
It’s an art form and your audiences attention is fleeting. I’ve worked with a lot of engineers that are long winded and every task becomes a dissertation and on the opposite side you have the helpless that can’t be bothered to read a simple wiki and want to be spoon fed.
ciscorick@reddit
First time?
j_yn0htna@reddit
Correct
failsafe-author@reddit
This is the way it has been for over 30 years in my experience.
uchiha007itachi@reddit
Well it's the era of reels and shorts. Attention to detail and attention spans have gone for a toss.
Wonderful_Device312@reddit
It's usually the result of documentation being out of date, incomplete, or just poorly written. I'm not passing judgement on your documentation but most documentation is an after thought and when I'm trying to understand a system my workflow is usually: skim the docs for a summary or overview then look at the code and play around with it a bit, if something doesn't make sense then I might look for an explanation in the docs.
I do have to remind myself to break out of that mindset occasionally when I'm dealing with things that have high quality documentation and in those cases, I've sometimes read through the entire documentation as bed time reading lol.
Also, there is a lot of information overload now days. I also have adhd, so if I'm struggling to focus on something, I won't be able to read the docs but a meeting might work better for me.
Tldr; lots of reasons.
RememberTheDarkHorse@reddit
Is there a TL;DR of this?
NeckBeard137@reddit
Could someone summarise the post for me, please?
Loose_Voice_215@reddit
I got promoted to team lead after 2 yoe, and I'm convinced that the main reason was because I was the only one reading the design docs in depth, asking follow-up questions, etc.
thodgson@reddit
Hell, I have meetings on my schedule with meaningless titles, zero agenda or description. I'd settle for one sentence! I've tried asking. I've tried pleading. I've tried declining meetings that don't have an agenda. The culture just doesn't GAF.
shifty_lifty_doodah@reddit
Depends a lot on workplace. People get good at what they practice. If the environment is rushed and impatient, people become rushed and impatient.
One solution is to refer people to the docs more. In the meeting, ask if they have questions about the doc, and give them time to read it. One of the things Amazon does well is start meetings by reading a document together.
lsdrunning@reddit
Yeah, I have found in the last year or so I have had to dumb things down a lot, use a lot of whitespace/bulleted lists, and re-emphasize certain points even for seemingly important/state changing communications.
Silver lining: I feel like it’s making me a better communicator
zuben_tell@reddit
I am going through the same problem. That and some people, instead of just asking questions on calls, now compare my answers to ChatGPT's answers live, sometimes questioning me over its hallucinations.
Competitive-Vast2510@reddit
Unfortunately, this is a side effect of Shorts, Reels and TikTok based consumption along with the overall mindset of "speed over everything" in the professional world.
We do not have the attention span and focus our predecessors have, and it's so unfortunate that we have to fight actively against the environment we live in to achieve a fraction of it.
nyki@reddit
Is the documentation searchable and easy to skim? Are there lots of code examples? No matter how good the information is, it's daunting to read and memorize long documents, especially when you only need part of it.
When I read documentation I almost always use text-to-speech because I can internalize things much faster by hearing them than by reading them. This is also why I find it faster to hop on calls to discuss. Plus the back and forth clears up any confusion and can point me in the direction of the info I actually need.
Personal preference of course, everyone is different, but many people won't feel like they have time to read an essay when they just need to get a task done.
Ok-Craft4844@reddit
One thing I observe for myself is that my motivation to read docs is very dependent on my trust in the thing documented and the parties involved.
Especially the last point can have unfair collateral damage, and will look what you described when it actually hits someone competent .
I'm aware that this isn't nice, and if the party proves trustworthy I will never bug then again, thank them, and remember I owe them one.
But in an environment where documentation is typically just the compliance magic needed to blame the users (i.e. basically every corporate job), I'm not willing to start with a leap of faith. Once bitten...
ryanheartswingovers@reddit
If your docs are just boring boiler, skipping. Get to the point.
xsdf@reddit
Some people consume information best audibly, personally I'm the opposite and prefer reading, but a meeting to go over information is the best way to get that information out to multiple people at the same time. If it's critical they know something then a meeting is best for forcing them to take it in as well. Perhaps try to consolidate these questions into one meeting rather than multiple meetings
Does your document include a table of contents with sections and subsections they can jump to? Or is it mostly just a wall of text? If you can link a subsection of the document you can answer questions easier
iPissVelvet@reddit
I have a small bit of educational background, one thing we learned in pedagogy class was everyone processes information in different ways. Think back to school when information was redundantly given to you in the form of verbal instruction, textbook reading, worksheets, videos, review packets, and tests (yeah, some people just learn from doing practice tests).
Obviously at work you don’t have the time to optimize information to be disseminated across all channels, but at least it helps you empathize. The other person isn’t necessarily stupid or lazy, they just prefer to process their information another way. I tend to accept two forms — written and verbal — and am happy to disseminate information in either format, depending on the other person’s preference.
Also, are you sure your writing is high quality and understandable? Writing is a skill, and writing coherently is a rare skill. I’ve had times where engineers will send me a long explanation and it doesn’t connect or flow at all. Then I have to ask for a live meeting where I have to fill in the blanks. To the other person this may seem like regurgitation — but they’re not remembering the small details they’ve forgotten to add.
janyk@reddit
One other thing I learned about how people learn wasn't just about the medium in which information is presented but in how people choose to represent the world they learn about as mental models or as lists of facts.
Mappers vs packers, as this article refers to them as.
I tend to construct mental models of the world and instruct people by describing the mental model. I also like reading documentation and manuals that convey principles and fundamentals of how and why things work. Others often want just simple facts about the world and their questions demand immediate answers about the topic at hand, without regard for a model that describes why it is true and may answer future questions they have about the topic.
Software development is about modeling facts about the world in software. You need modelers (a.k.a. mappers), not packers, to do it well.
realhenrymccoy@reddit
This bugs me all the time. I also like to write out my thoughts on complex topics in emails, documentation, ticket updates etc. I’ll spend time laying everything out in an email and it’s like no one even reads it. Just end up having to setup a call to explain exactly what I wrote.
I’m much better at being able to explain my thoughts via text though so if people want to listen to me stumble over words on a call so be it.
finns96@reddit
Drives me nuts. Especially for highly technical teams (talking from experience) there is no excuse to not be capable of reading longer-form text (sometimes its not even that much text, but specific and nuanced in terms of its importance or detail)
It's part of your job to understand highly technical information. If you cannot take the time or don't have the attention span to even read what has been written, you probably should not have that job.
commonsearchterm@reddit
Two sides to this though.
Long docs can be pretty bad too. Poorly written documentation is basically the same as no documentation. There is a lot that goes into making some readable and easy to understand.
Its the reason you use paragraphs and people will bitch endlessly if you write a comment on the interest as a wall of text.
My current company is like this though, i don't know why they think its ok. I get no context fully complete PRs they think is mergeable, staff engineers use bad grammar and wont format things. Its crazy to see. I dont understand, the level of "engineering" is wild to experience.
mr_ryh@reddit
People are perversely incentivized not to read since it gives them an excuse to have more meetings and thus pad ("account") for their time without actually doing anything productive.
Maybe you can document how much time is lost by people asking questions that they could've answered themselves by RTFM. Compile the report up quarterly, quantifying approximately how much it's costing the company, aggregating the data so there's no politics involved (at least in the public report). Go to your boss with it, and see if you two together can devise a pitch to a Director/VP/SVP/COO/etc. to push for cost-saving reforms (e.g. "before asking a question or holding a meeting, write your questions down and post them to this forum", etc.), possibly including discipline of any recalcitrant frequent offenders.
SiSkr@reddit
This has always been somewhat of an issue, and is just more exacerbated nowadays by a general preference for short form and quick fixes. It's one of the reasons a company I used to work for introduced Amazon's document driven meetings, and it actually worked pretty great!
It not only makes people get on the same page (literally) before discussing, but also forces the actual meeting-holder to write up a doc instead of just willy-nilly calling a meeting and waiting people's time faffing about.
tallgeeseR@reddit
At one point i was regularly working 12-16hrs a day for projects with compressed deadline. I really hope someone could help answer my doubts rather than having to go through docs.
Some folks are simply lazy. Some would happily take advantage of others.
It's really case by case.
Perhaps time to start experimental project, self host AI, feed your docs to it 😛
brotherkin@reddit
Yeah written docs don’t seem to carry the same weight anymore
These days I generally rely on examples in sandboxes or I might do a video explaining my system or both. I’m a game dev so it’s probably a little different but those methods have had much better success than just regular ole written docs
Trick-Interaction396@reddit
Use AI to turn your notes into a doc so your colleagues can use AI to summarize you doc
tinmanjk@reddit
Read "Amusing Ourselves to Death" by Neil Postman
micseydel@reddit
This is definitely a real issue https://www.forbes.com/sites/ryancraig/2024/11/15/kids-cant-read-books/
Whenever I see posts like this, I think I'm scientific editorial https://www.nejm.org/doi/full/10.1056/NEJMe2400189 though maybe it's mostly an AI problem 🤷♂️
Antilock049@reddit
If people aren't reading them, they're probably not great docs.
i-think-about-beans@reddit
This is why I ask a simple question and instead of a written answer I can go back to later I get “quick call?”
SituationSoap@reddit
"People don't read" has been my #1 guiding mantra in tech for the full 20 ish years of my career. It hasn't failed me yet.
Unlucky_Buy217@reddit
As a dev who has been on both sides of this conversation, with docs going unread and me not reading them. It's literally only because we have limited time, and docs like this are long and require truly focused reading, not to mention more often that not, you also need to brush up on additional context by reading other docs if it's a new project or slightly unrelated to your work. People are already swamped with tasks assigned to their name and then you being these docs to the fray and ask people to read it when it's not accounted for in their work time. You can at least mention or call out that a you were in a meeting when you read a doc during the meeting but spending 1-2 hours reading a single doc when its not accounted for in the work day, no one has the time for that.
prisencotech@reddit
I've suggested creating video tutorials instead of docs because of this. Getting people to read has always been a struggle but lately it's gotten even worse.
xlb250@reddit
I prefer discussing in meetings tbh. What’s obvious to me may not be obvious to others.
elykl33t@reddit
Personally I'm the opposite just because I like to compose questions I might have, and half the time I answer it for myself as I type everything out and cross-reference with the docs.
Which I guess regardless means people who work like me aren't really part of the problem here.
Kindly_Climate4567@reddit
Yes, but you should still read the doc before the meeting
Important-Product210@reddit
I write TODOs of what I do later on. 20 TODOS in the code translates to: get back to this after X is finished or Y is fixed on vendor Z. Workarounds are nasty. Maybe the design is faulty and would benefit of simplification.
drakeallthethings@reddit
Capable? absolutely. When other teams ask questions about our products and I direct them to the documents they could’ve accessed this whole time but didn’t, they’re able to read them just fine.
CVisionIsMyJam@reddit
You need hiring and firing power to at least control for the team you're on being literate.
I work remote first and I think that helps.
I actually do feel like people are pressured to not read docs or long text though. Like, we use tools but don't always get time to understand how they work, we just have to go in, get what we need, make the changes we need, then get out. it does lead to a patchwork model of understanding.
talldean@reddit
If it's long, especially 10+ pages, then generally no. You have 3-5 pages of attention, tops.
If you put a 1-3 page FAQ linking to sections, you may get more; they see their question before running out of attention, and then can go to the correct answer.
duddnddkslsep@reddit
It's because we're in the era of short-form video, where everyone's attention span has been reduced to 2-3 seconds.
Blame TikTok
SuperSuperKyle@reddit
I write docs for everything as well, and this is just going to be team dependent. None of the other teams have documentation for their projects or repos so it's frustrating. Have them install Copilot or Code Buddy or something to have AI describe the code base and read the docs for them:
https://codebuddy.ca/
They can ask all the questions they want there.
This could also be a documentation issue. Sometimes less is more, or providing more examples helps when there isn't any and they just have a wall of text.
It's an endless struggle though so I feel your frustration.
blbd@reddit
Were they ever capable?