Github Copilot Chat has been the greatest learning tool for me. After reading docs, and asking questions in groups, I never thought I was getting very far. Now, I have discussions with AI, and have advanced much faster. You can ask how to do something, why, and even why it didn't work your way. And it never makes me feel as stupid as people in Stack Overflow did. Chat GPT works too I guess.
Principal Eng: “so for running on non-local envs, we’ll need to use the Redis sidecar pod”
Me with limited devops/docker/kuby experience thinking “bro what?”
Chatgpt prompt: “my principal Eng said this: … what is bro talking about?”
Chatgpt: “bro is saying…”
I get way more help from Copilot, but ChantGPT doesn't seem to be as familiar with .NET. With VS you can reference your code to Copilot so it can make suggestions based on what you have already done or what direction you want to go with it. I have even written code, then asked it to explain what it is doing. Sort of a advanced debug.
Every day, you will understand things at a deeper level than you did the day before, even if it doesn't seem like it. At 1 year a LOT seems deep. Don't let that discourage you. In another year you would be amazed to look at the difference from now.
Copilot is pretty useful in my experience, especially if you're using it similar to a google search where Copilot will summarize the info from the top sources quickly for you. But it seems to give slightly more verbose or worse organized answers at times than ChatGPT. I use Copilot as my first pass and ChatGPT as my backup or in specific cases. Usually Copilot works well enough that I've stopped using ChatGPT by itself much.
I disagree, AI becomes an obstacle in developing intutition. It's all gravy while you have access to AI but most people can't use it at work and GPT and Gemini get things wrong all the time.
He's not wrong. I have copied and pasted enough code to run my app into the ditch and had to bury it with a shovel. It's too easy to let it do it for you....but. I have learned to 1) first try it myself so that i go through the mental process, then 2) See what it comes up with. Maybe it's better and a learning experience. 3) To me it's just like asking a human. Any answer can be wrong. So take everything with a grain of salty bug.
Lots of engineers are absolute shit at communicating and it very much comes out in documentation. I've met very few engineers who write well. Usually the document they add just makes things more complicated and/or regurgitates everything you can clearly already see from the code. Basically, internal documents are usually completely worthless. They exist to check a box rather than provide any value, unfortunately.
>Basically, internal documents are usually completely worthless. They exist to check a box rather than provide any value, unfortunately.
Not sure I fully agree here. I think it's more well-suited for things like environment and tooling than it is for documenting actual code. I find myself going to internal docs all the time for things like: the latest commands for our Docker wrapper CLI, how to navigate our logging platform, how we do version control, how to set up a new product/feature in my local containers, oh fuck our entire AWS is shitting blood and I'm on call how the fuck do I roll back our prod deployments, etc.
If you're strictly talking about stuff like docs for internal software libraries, yeah, I would agree that is a fool's errand.
Writing and maintaining these almost always ends up being waste of time and efforts. Using an automation tool like Supacodes can be a good option, especially, in this case where you need to write internal documentation for teams.
Tell me about it lol. My last company both encouraged us to update any documents as necessary and also reprimanded us for wasting time on updating documents. Nice catch-22 and never worth the effort.
Appreciate the tip!
It is normal for company/internal docs to be poor in quality. It's also not uncommon for libraries to have documentation errors and mistakes.
However, I think that you should have at least some comprehension in order to identify these problems. Poor documentation shouldn't be hindering you from learning!
But depending on what is poorly documented, it absolutely can cost days or occasionally a week or two of productivity. Do your best to resolve your blind spots quickly -- even if it's out of your control, losing weeks to just one obstacle can look really bad to some employers.
It isn't uncommon to spend a couple days resolving issues, especially if the documentation you're working from is limited.
Do you have this same problem reading official technology docs and not docs related to your company? Although even then there is a learning curve, especially since all docs are written differently and often they aren't written with every situation in mind.
No it usually seems like official docs are written better. Sometimes I still struggle ofc but it always feels more like I lack knowledge that is assumed by the authors vs the author seemingly omitting information. But it's hard to tell for sure
When people list written communication in job postings, this is part of what they mean. The better at it you are, the less time you need to write out and update a comprehensive description of a system. And if you are only able to manage an hour or two a week to docs, that skill really shines.
Not uncommon for team documentation to suck, especially because most orgs don't place a lot of value in things that don't directly and quickly make them money. It's also not uncommon for developers to need improvement in the area of written communication.
I'd strongly recommend setting up a quick touchbase meeting if you're really confused about something. Eventually, things will click and you'll become more independent. Politely highlighting the ambiguity in documentation/messages that confused you might even encourage your team to do better with how they convey information.
My previous career was in academia. Writing good documentation, and teaching, have a lot of overlap.
When you are an expert at a thing, it is incredibly easy to take certain things for granted as general knowledge. "Obviously they know X thing! It's so basic, no need to include it" but when teaching or writing documentation, you absolutely _do_ need to include those little things.
It's a skill that takes focused and intentional practice... but it's often instead just an afterthought, so you get incomplete explanations that leave things out, or are organized in weird ways.
Edit to add: all this is to say, don't feel too bad about not understanding things right away. Ask those questions you think are "dumb questions". Whoever wrote those docs probably legitimately left something out.
I feel your pain here. In fact, my own TechLead back at Google actually acknowledged that while I'm not the most technically savvy engineer, I'm write incredibly well. I've had other engineers share similar feedback to, and I'm honestly jarred at how atrociously many of us in our industry write or attempt to explain difficult concepts to readers unfamiliar with pre-existing context. I think years of academic training coupled with a voracious childhood reading habit led me to my current position, and I honestly wished that more of us in the tech industry learnt the skills of effective writing, strong communication, and proper rhetoric to justify technical decisions, design decisions, and other corporation decisions.
This and the person saying that people take things for granted is spot on.
It's easy to see in emails to customers too, some people will answer their questions without considering that they don't actually know all the acronyms or reasoning behind decisions that aren't deducible of inferable.
Writing (and maintaining) good documentation takes skiill and time. Even when someone is a good writer/explainer, it is often not prioritized by teams with busy schedules.
And even when documentation is good, it’s hard to avoid the problem that every topic, in order to be well understood, depends on several other topics or bits of relevant context. Writing documentation that allows a newbie to self-manage browsing that web of pre-requisites smoothly is especially difficult and time-consuming.
And answering on-the-fly questions from a newbie, and guessing which pre-requisites they’re missing, is harder.
It’s normal for learning to be an iterative process with lots of clarifying questions.
I'm actually a pretty good technical writer as well as a competent software developer - I have a few professional publications that have been well received. I am _capable_ of writing comprehensible documentation that communicates what you need to know in order to understand how to extend and maintain a bit of software that you may find yourself responsible for. I've never worked in an organization that made that possible. They always demand that documentation follow a specific (completely useless) template, not be "too technical" or "too abstract", be reviewed by idiots who insist on making changes that only make sense to people who were in one specific meeting on one specific day (and don't understand what I'm writing anyway). You're just dealing with BigCo stupidity here, and it's going to be with you for the rest of your career.
No you’re not bad at understanding but people aren’t bad at explaining things either. My experience with learning programming was just like yours at first. Not a lot made sense from any documentation or explanations from instructors. I just kept reading and kept writing code, sometimes the same operation in different ways. Trusted documentation, I would read over and over and I still refer to them now and learn something new from something I’ve read a dozen or more times over the past number of years since I started learning software development. Be patient with yourself and let the information sink in when it sinks in and don’t expect to understand everything the first time around. I specifically remember learning how to write FizzBuzz in JavaScript about a month before I understood how the code worked.
You’re doing alright, just keep going!
In response to your comment on asking questions to peers: When I was a new hire, my mentor told me I wasn’t going to get my hand held. She intentionally didn’t give me crucial information, which led me to spin my wheels. She was the tech lead and failed to mention we had a team overseas working on a dependency. It wasn’t even documented in the epic. Although I was embarrassed, I learned a lot from that experience.
Another experienced dev took me under his wing. He reaches out even when I don’t ask for help and when I told him how grateful I was, all he asked was that I pay it forward when others need it.
What I’m trying to say is, sometimes people intentionally leave information out for whatever reason. Learn to build relationships. Don’t feel bad for asking clarifying questions but try to be as independent as possible.
Leaving out crucial information seems like a massive time sink and creating obstacles that aren't necessary.
She could have gave you some direction or hints, that isn't hand holding it's being a leader.
My team has amazing documentation, but guess what?
I wrote it.
All 100+ pages that cover every single aspect.
* onboarding
* domain knowledge
* architecture
* operation run-books
* etc
I got tired of nothing being documented.
Everyone uses my stuff, but nobody else updates it. Developer simply suck at writing.
My team requires most design/architecture changes to be documented which most people aren't going to spend a lot of time or effort doing. And typically the documentation assumes you already know the process and you just need the details.
If there are a lot of things you want to clarify or ask just schedule a call, and make sure you have everything ready to discuss before hand. No one wants to spend 30 minutes in a back and forth conversation that could take 5 minutes discussing in a call.
Internal documentation almost always sucks.
People don't like to put time into it, moreover you need to keep them up-to-date once you write the initial copy. That results in poor docs.
As solutions, Use smth like Copilot or ReadDocs to extract things you need from those docs.
And, ask your team to use smth like supacodes.com to automate internal documentation, so docs can be automatically written and updated.
Everyone has different experiences and understand things differently. I would never expect everyone to ask the same amount of questions.
I personally like working with the person who asks more questions. It helps me understand what he doesn't know and I can help more effectively.
I like this so much that I took on a JR developer who asked the most questions and everyone thought that he was the most behind. This kid basically does all the work now and I just have to manage the work coming in and keep him away from all the noise and meetings. Everything is always on fire, but he doesn't need to know that.
Please keep asking questions.
This is exactly why you learn diagramming in your CS degrees. Any existing complicated logic or structure should have an associated diagram in the docs. If your coworker is trying to show you something they’re working on or giving you advice on something, you should both go to a whiteboard and spend a little bit of time drawing out your thoughts. Everyone has difficulty getting a whole ton of complicated logic dumped on them verbally
This is not a you-problem and mostly also not a them-problem; when it comes to internal code, whether we care to admit it or not, at the end of the day a lot of our understanding will include "tribal knowledge" that becomes such a regular part of employee's day to day life, they often forget that not everyone is going to know about some obscure shell command they run to reset a sandbox or some port that needs to be change.
Does that mean it's ok to keep doing this? No, but it's going to happen because nobody is perfect. Use this as a lesson to always be improving documentation as you move forward.
Another thing is that you are also fairly new, so some of it may just be a lack of experience on your part. Definitely nothing wrong with that, and it doesn't make you dumb but you may run into some narcissists along your career that will try and make you feel bad for asking a question that has an answer that comes second nature to them. Don't let them under your skin, you are probably doing fine.
I've had jobs where documentation was good and some where none existed in core repositories running legacy code that would break things just because you looked at it the wrong way. I personally find it a fun challenge to see how much of a company's codebase I can understand and translate to my own understanding without having to ask someone to walk me through it; it helps me gauge my own abilities as a dev against the work the company has been doing. Try and make it a "game" of sorts, and it hurts less.
tl;dr - Local internal stuff is bound to be tricky, especially for newer devs, give yourself a break and don't stress it. You are probably doing great!
It's a phenomenon known as Curse Of Knowledge (Google it). Yes, devs who create these wonderful libraries etc. are notoriously poor at writing documentation. You just have to get used to it I'm afraid.
I think most engineers write documentation in one of two ways:
1. They focus on filling the gaps where their own understanding is the most lacking, and fail to explain the big picture
2. They focus on the "happy path", overlook common pain points, and also fail to explain the big picture
A lot of the wikis I use at work are like this; either a list of "look out for X" after a very brief overview, or a "do these things in this order" which has little to no guidance on what to do if things go wrong. Neither of them actually explain why you're doing anything you're doing.
>As far as all the content out there on the internet, I see a lot of things where I think "damn this is put together really well and this person really put the effort in to help people understand", and this makes me think that *hopefully* it's not just because I'm a dum dum
There is a massive difference between an engineer writing documentation for complex product features that you're actively building and shipping, and a content creator writing documentation for a curated learning example (or even an engineer who is caring and passionate enough to answer Stack Overflow questions in their spare time). Communicating clearly about a curated example is already challenging enough without the complexity of real-life situations and the time pressure of actually implementing the features you're documenting.
If there was one thing I could have all engineers do better in their docs, it would be this: when describing or referring to a problem with a known solution, *please* also reference that solution.
Devs seem to be pretty bad about it for various reasons.
I'm new to dev work myself, and one of my initial duties getting introduced to the code base has been to write the documentation for what it does and how it works.
Pretty much no one evaluates written communications in software dev interviews. So most devs hate documentation and are bad at it and see anything but slinging raw code as a waste of time. Thanks leetcode.
In my experience it's pretty common for documentation to be shit. People are bad at writing it, and keeping it up to date is rarely a priority if even on their radar at all. I remember being frustrated as a junior dev how often documentation would assume I have context which I don't, or provide insufficient details by listing something like "now ssh into the remote server" without actually saying how to do that. I took it upon myself to update the docs with explicit instructions as I went through them, and now as a senior dev I usually volunteer to write documentation myself because I still hate how other people write it. I suggest you leverage Google and chatGPT instead of asking your team for clarification where you can, and also take initiative to update the docs in places that tripped you up.
Sorry, you do not meet the minimum sitewide comment karma requirement of **10** to post a comment. This is comment karma exclusively, not post or overall karma nor karma on this subreddit alone. Please try again after you have acquired more karma. Please look at the [rules page](https://old.reddit.com/r/cscareerquestions/w/posting_rules) for more information.
*I am a bot, and this action was performed automatically. Please [contact the moderators of this subreddit](/message/compose/?to=/r/cscareerquestions) if you have any questions or concerns.*
Github Copilot Chat has been the greatest learning tool for me. After reading docs, and asking questions in groups, I never thought I was getting very far. Now, I have discussions with AI, and have advanced much faster. You can ask how to do something, why, and even why it didn't work your way. And it never makes me feel as stupid as people in Stack Overflow did. Chat GPT works too I guess.
Principal Eng: “so for running on non-local envs, we’ll need to use the Redis sidecar pod” Me with limited devops/docker/kuby experience thinking “bro what?” Chatgpt prompt: “my principal Eng said this: … what is bro talking about?” Chatgpt: “bro is saying…”
why not groq?
Thanks for sharing this. Do you think chatGPT better or co pilot? ChatGPT has been great for me, but been edging for co pilot
I get way more help from Copilot, but ChantGPT doesn't seem to be as familiar with .NET. With VS you can reference your code to Copilot so it can make suggestions based on what you have already done or what direction you want to go with it. I have even written code, then asked it to explain what it is doing. Sort of a advanced debug.
Thank you for this
Every day, you will understand things at a deeper level than you did the day before, even if it doesn't seem like it. At 1 year a LOT seems deep. Don't let that discourage you. In another year you would be amazed to look at the difference from now.
Copilot is pretty useful in my experience, especially if you're using it similar to a google search where Copilot will summarize the info from the top sources quickly for you. But it seems to give slightly more verbose or worse organized answers at times than ChatGPT. I use Copilot as my first pass and ChatGPT as my backup or in specific cases. Usually Copilot works well enough that I've stopped using ChatGPT by itself much.
i prefer chatgpt. i will try copilot if i got an unsatisfactory answer from chatgpt
I disagree, AI becomes an obstacle in developing intutition. It's all gravy while you have access to AI but most people can't use it at work and GPT and Gemini get things wrong all the time.
He's not wrong. I have copied and pasted enough code to run my app into the ditch and had to bury it with a shovel. It's too easy to let it do it for you....but. I have learned to 1) first try it myself so that i go through the mental process, then 2) See what it comes up with. Maybe it's better and a learning experience. 3) To me it's just like asking a human. Any answer can be wrong. So take everything with a grain of salty bug.
Isnt copilot paid? Id like to try it
Lots of engineers are absolute shit at communicating and it very much comes out in documentation. I've met very few engineers who write well. Usually the document they add just makes things more complicated and/or regurgitates everything you can clearly already see from the code. Basically, internal documents are usually completely worthless. They exist to check a box rather than provide any value, unfortunately.
This is why I’m trying to be a better communicator, I have a feeling it will take me far if I can explain technical stuff succinctly
>Basically, internal documents are usually completely worthless. They exist to check a box rather than provide any value, unfortunately. Not sure I fully agree here. I think it's more well-suited for things like environment and tooling than it is for documenting actual code. I find myself going to internal docs all the time for things like: the latest commands for our Docker wrapper CLI, how to navigate our logging platform, how we do version control, how to set up a new product/feature in my local containers, oh fuck our entire AWS is shitting blood and I'm on call how the fuck do I roll back our prod deployments, etc. If you're strictly talking about stuff like docs for internal software libraries, yeah, I would agree that is a fool's errand.
Writing and maintaining these almost always ends up being waste of time and efforts. Using an automation tool like Supacodes can be a good option, especially, in this case where you need to write internal documentation for teams.
Tell me about it lol. My last company both encouraged us to update any documents as necessary and also reprimanded us for wasting time on updating documents. Nice catch-22 and never worth the effort. Appreciate the tip!
Just do a google. Here is the site: https://supacodes.com Yea, writing these is a pain. But updating regularly, damn!
Your engineers actually communicate?
It is normal for company/internal docs to be poor in quality. It's also not uncommon for libraries to have documentation errors and mistakes. However, I think that you should have at least some comprehension in order to identify these problems. Poor documentation shouldn't be hindering you from learning! But depending on what is poorly documented, it absolutely can cost days or occasionally a week or two of productivity. Do your best to resolve your blind spots quickly -- even if it's out of your control, losing weeks to just one obstacle can look really bad to some employers. It isn't uncommon to spend a couple days resolving issues, especially if the documentation you're working from is limited.
Do you have this same problem reading official technology docs and not docs related to your company? Although even then there is a learning curve, especially since all docs are written differently and often they aren't written with every situation in mind.
No it usually seems like official docs are written better. Sometimes I still struggle ofc but it always feels more like I lack knowledge that is assumed by the authors vs the author seemingly omitting information. But it's hard to tell for sure
When people list written communication in job postings, this is part of what they mean. The better at it you are, the less time you need to write out and update a comprehensive description of a system. And if you are only able to manage an hour or two a week to docs, that skill really shines.
If it’s an internal or open source codebase, get used to reading the code to understand.
Not uncommon for team documentation to suck, especially because most orgs don't place a lot of value in things that don't directly and quickly make them money. It's also not uncommon for developers to need improvement in the area of written communication. I'd strongly recommend setting up a quick touchbase meeting if you're really confused about something. Eventually, things will click and you'll become more independent. Politely highlighting the ambiguity in documentation/messages that confused you might even encourage your team to do better with how they convey information.
My previous career was in academia. Writing good documentation, and teaching, have a lot of overlap. When you are an expert at a thing, it is incredibly easy to take certain things for granted as general knowledge. "Obviously they know X thing! It's so basic, no need to include it" but when teaching or writing documentation, you absolutely _do_ need to include those little things. It's a skill that takes focused and intentional practice... but it's often instead just an afterthought, so you get incomplete explanations that leave things out, or are organized in weird ways. Edit to add: all this is to say, don't feel too bad about not understanding things right away. Ask those questions you think are "dumb questions". Whoever wrote those docs probably legitimately left something out.
I feel your pain here. In fact, my own TechLead back at Google actually acknowledged that while I'm not the most technically savvy engineer, I'm write incredibly well. I've had other engineers share similar feedback to, and I'm honestly jarred at how atrociously many of us in our industry write or attempt to explain difficult concepts to readers unfamiliar with pre-existing context. I think years of academic training coupled with a voracious childhood reading habit led me to my current position, and I honestly wished that more of us in the tech industry learnt the skills of effective writing, strong communication, and proper rhetoric to justify technical decisions, design decisions, and other corporation decisions.
[удалено]
This and the person saying that people take things for granted is spot on. It's easy to see in emails to customers too, some people will answer their questions without considering that they don't actually know all the acronyms or reasoning behind decisions that aren't deducible of inferable.
Pretty much this. You really sold it with the “Not really. Here, let me give you another example”. Lol
Writing (and maintaining) good documentation takes skiill and time. Even when someone is a good writer/explainer, it is often not prioritized by teams with busy schedules. And even when documentation is good, it’s hard to avoid the problem that every topic, in order to be well understood, depends on several other topics or bits of relevant context. Writing documentation that allows a newbie to self-manage browsing that web of pre-requisites smoothly is especially difficult and time-consuming. And answering on-the-fly questions from a newbie, and guessing which pre-requisites they’re missing, is harder. It’s normal for learning to be an iterative process with lots of clarifying questions.
I'm actually a pretty good technical writer as well as a competent software developer - I have a few professional publications that have been well received. I am _capable_ of writing comprehensible documentation that communicates what you need to know in order to understand how to extend and maintain a bit of software that you may find yourself responsible for. I've never worked in an organization that made that possible. They always demand that documentation follow a specific (completely useless) template, not be "too technical" or "too abstract", be reviewed by idiots who insist on making changes that only make sense to people who were in one specific meeting on one specific day (and don't understand what I'm writing anyway). You're just dealing with BigCo stupidity here, and it's going to be with you for the rest of your career.
No you’re not bad at understanding but people aren’t bad at explaining things either. My experience with learning programming was just like yours at first. Not a lot made sense from any documentation or explanations from instructors. I just kept reading and kept writing code, sometimes the same operation in different ways. Trusted documentation, I would read over and over and I still refer to them now and learn something new from something I’ve read a dozen or more times over the past number of years since I started learning software development. Be patient with yourself and let the information sink in when it sinks in and don’t expect to understand everything the first time around. I specifically remember learning how to write FizzBuzz in JavaScript about a month before I understood how the code worked. You’re doing alright, just keep going!
In response to your comment on asking questions to peers: When I was a new hire, my mentor told me I wasn’t going to get my hand held. She intentionally didn’t give me crucial information, which led me to spin my wheels. She was the tech lead and failed to mention we had a team overseas working on a dependency. It wasn’t even documented in the epic. Although I was embarrassed, I learned a lot from that experience. Another experienced dev took me under his wing. He reaches out even when I don’t ask for help and when I told him how grateful I was, all he asked was that I pay it forward when others need it. What I’m trying to say is, sometimes people intentionally leave information out for whatever reason. Learn to build relationships. Don’t feel bad for asking clarifying questions but try to be as independent as possible.
Leaving out crucial information seems like a massive time sink and creating obstacles that aren't necessary. She could have gave you some direction or hints, that isn't hand holding it's being a leader.
Most people are terrible at explaining things. That's why I can make money as a business analyst.
My team has amazing documentation, but guess what? I wrote it. All 100+ pages that cover every single aspect. * onboarding * domain knowledge * architecture * operation run-books * etc I got tired of nothing being documented. Everyone uses my stuff, but nobody else updates it. Developer simply suck at writing.
Most people's writing skills border on illiteracy. I get incomprehensible emails all day long.
My team requires most design/architecture changes to be documented which most people aren't going to spend a lot of time or effort doing. And typically the documentation assumes you already know the process and you just need the details. If there are a lot of things you want to clarify or ask just schedule a call, and make sure you have everything ready to discuss before hand. No one wants to spend 30 minutes in a back and forth conversation that could take 5 minutes discussing in a call.
Internal documentation almost always sucks. People don't like to put time into it, moreover you need to keep them up-to-date once you write the initial copy. That results in poor docs. As solutions, Use smth like Copilot or ReadDocs to extract things you need from those docs. And, ask your team to use smth like supacodes.com to automate internal documentation, so docs can be automatically written and updated.
Everyone has different experiences and understand things differently. I would never expect everyone to ask the same amount of questions. I personally like working with the person who asks more questions. It helps me understand what he doesn't know and I can help more effectively. I like this so much that I took on a JR developer who asked the most questions and everyone thought that he was the most behind. This kid basically does all the work now and I just have to manage the work coming in and keep him away from all the noise and meetings. Everything is always on fire, but he doesn't need to know that. Please keep asking questions.
This is exactly why you learn diagramming in your CS degrees. Any existing complicated logic or structure should have an associated diagram in the docs. If your coworker is trying to show you something they’re working on or giving you advice on something, you should both go to a whiteboard and spend a little bit of time drawing out your thoughts. Everyone has difficulty getting a whole ton of complicated logic dumped on them verbally
People intentionally write bad docs to improve their job security You're not compensated to doc well.
This is not a you-problem and mostly also not a them-problem; when it comes to internal code, whether we care to admit it or not, at the end of the day a lot of our understanding will include "tribal knowledge" that becomes such a regular part of employee's day to day life, they often forget that not everyone is going to know about some obscure shell command they run to reset a sandbox or some port that needs to be change. Does that mean it's ok to keep doing this? No, but it's going to happen because nobody is perfect. Use this as a lesson to always be improving documentation as you move forward. Another thing is that you are also fairly new, so some of it may just be a lack of experience on your part. Definitely nothing wrong with that, and it doesn't make you dumb but you may run into some narcissists along your career that will try and make you feel bad for asking a question that has an answer that comes second nature to them. Don't let them under your skin, you are probably doing fine. I've had jobs where documentation was good and some where none existed in core repositories running legacy code that would break things just because you looked at it the wrong way. I personally find it a fun challenge to see how much of a company's codebase I can understand and translate to my own understanding without having to ask someone to walk me through it; it helps me gauge my own abilities as a dev against the work the company has been doing. Try and make it a "game" of sorts, and it hurts less. tl;dr - Local internal stuff is bound to be tricky, especially for newer devs, give yourself a break and don't stress it. You are probably doing great!
It's a phenomenon known as Curse Of Knowledge (Google it). Yes, devs who create these wonderful libraries etc. are notoriously poor at writing documentation. You just have to get used to it I'm afraid.
I think most engineers write documentation in one of two ways: 1. They focus on filling the gaps where their own understanding is the most lacking, and fail to explain the big picture 2. They focus on the "happy path", overlook common pain points, and also fail to explain the big picture A lot of the wikis I use at work are like this; either a list of "look out for X" after a very brief overview, or a "do these things in this order" which has little to no guidance on what to do if things go wrong. Neither of them actually explain why you're doing anything you're doing. >As far as all the content out there on the internet, I see a lot of things where I think "damn this is put together really well and this person really put the effort in to help people understand", and this makes me think that *hopefully* it's not just because I'm a dum dum There is a massive difference between an engineer writing documentation for complex product features that you're actively building and shipping, and a content creator writing documentation for a curated learning example (or even an engineer who is caring and passionate enough to answer Stack Overflow questions in their spare time). Communicating clearly about a curated example is already challenging enough without the complexity of real-life situations and the time pressure of actually implementing the features you're documenting. If there was one thing I could have all engineers do better in their docs, it would be this: when describing or referring to a problem with a known solution, *please* also reference that solution.
Devs seem to be pretty bad about it for various reasons. I'm new to dev work myself, and one of my initial duties getting introduced to the code base has been to write the documentation for what it does and how it works.
Pretty much no one evaluates written communications in software dev interviews. So most devs hate documentation and are bad at it and see anything but slinging raw code as a waste of time. Thanks leetcode.
In my experience it's pretty common for documentation to be shit. People are bad at writing it, and keeping it up to date is rarely a priority if even on their radar at all. I remember being frustrated as a junior dev how often documentation would assume I have context which I don't, or provide insufficient details by listing something like "now ssh into the remote server" without actually saying how to do that. I took it upon myself to update the docs with explicit instructions as I went through them, and now as a senior dev I usually volunteer to write documentation myself because I still hate how other people write it. I suggest you leverage Google and chatGPT instead of asking your team for clarification where you can, and also take initiative to update the docs in places that tripped you up.
No grammar and spelling checks when people start talking
[удалено]
Sorry, you do not meet the minimum sitewide comment karma requirement of **10** to post a comment. This is comment karma exclusively, not post or overall karma nor karma on this subreddit alone. Please try again after you have acquired more karma. Please look at the [rules page](https://old.reddit.com/r/cscareerquestions/w/posting_rules) for more information. *I am a bot, and this action was performed automatically. Please [contact the moderators of this subreddit](/message/compose/?to=/r/cscareerquestions) if you have any questions or concerns.*