Skip to content

Commit

Permalink
Fix typo
Browse files Browse the repository at this point in the history
  • Loading branch information
AleksandrHovhannisyan committed Dec 2, 2022
1 parent c32a1cd commit c72ed70
Showing 1 changed file with 2 additions and 2 deletions.
4 changes: 2 additions & 2 deletions src/_posts/2022-11-05-writing-better-documentation/index.md
Expand Up @@ -11,11 +11,11 @@ A few years ago, I had a memorable interview experience where I was asked this s

Documentation is one of those things that you don't appreciate until you have to work without it—trying to make sense of a code base, library, or API without documentation can be a very stressful and overwhelming experience, and it can cause all sorts of problems for your team. In the absence of documentation, your developers may become hyper-specialized, where only one or two team members are comfortable touching an area of the code base and everyone else is afraid to get anywhere near it. Missing documentation also makes it more difficult for new developers to contribute, so they may need to regularly ask for help or spend more time adjusting to the team than they normally would. The lack of documentation may even discourage new developers from joining your team.

For new hires especially, navigating the onboarding process can already feel like like learning a new language in a new country: You need to complete HR paperwork, watch training videos, set up your work equipment (which you hopefully already have), get your local environment up and running (you do have GitHub access, don't you?), read your team's documentation (which hopefully exists), fix any issues you encounter along the way (oh, they're not documented?), and try not to have a mental breakdown. Your first few days are likely going to be stressful no matter how well you plan ahead. Unfortunately, the lack of documentation compounds that stress.
For new hires especially, navigating the onboarding process can already feel like learning a new language in a new country: You need to complete HR paperwork, watch training videos, set up your work equipment (which you hopefully already have), get your local environment up and running (you do have GitHub access, don't you?), read your team's documentation (which hopefully exists), fix any issues you encounter along the way (oh, they're not documented?), and try not to have a mental breakdown. Your first few days are likely going to be stressful no matter how well you plan ahead. Unfortunately, the lack of documentation compounds that stress.

Typically, you'll likely be expected to ramp up quickly enough to be able to submit your first small contributions within a few weeks. Meanwhile, your coworkers are going to be busy trying to meet their own deadlines (unless you're assigned a dedicated mentor). Especially if you're just starting out in your career, you might feel like a child in the presence of giants, timidly tugging on their sleeves to get their attention without incurring their wrath. This ramp-up period can be difficult not only because you have so much to do and learn but also because you're under immense pressure to not disappoint or bother your coworkers. I know what it's like to be the new hire who posts a laundry list of questions in Slack and feels compelled to apologize in advance for inconveniencing the team. But I also know how invaluable documentation can be for a seamless onboarding period.

Once you've been on your team long enough, you may begin to forget what it was like when you first joined. But the hiring process doesn't stop with you: A new cohort of developers will eventually join your team, and they'll go through the same trials and tribulations that you endured just a few years back. Nobody can point out shortcomings on your team quite so well as new hires can. While you and your coworkers are already comfortable with the code base and your work process, new hires may struggle to adjust. Your developers may need to spend more time than usual helping their coworkers and answering the same set of commonly asked questions, and these inefficiencies will worsen unless something changes.
Once you've been on your team long enough, you may begin to forget what it was like when you first joined. But the hiring process doesn't stop with you: A new cohort of developers will eventually join your team, and they'll go through the same trials and tribulations that you endured just a few years back. Nobody can point out shortcomings on your team quite as well as new hires can. While you and your coworkers are already comfortable with the code base and your work process, new hires may struggle to adjust. Your developers may need to spend more time than usual helping their coworkers and answering the same set of commonly asked questions, and these inefficiencies will worsen unless something changes.

For all these reasons and more, documentation is essential to the health of a software team. Good documentation not only helps your seasoned developers to navigate unfamiliar areas of the product and amass more domain knowledge, but it also helps newcomers to get up and running more quickly and familiarize themselves with your team. While it's true that documentation requires time and effort to create as well as maintain, it's an investment in your team: The more high-quality documentation you write, the better equipped your team will be to tackle existing and future problems, and the less time you'll waste chasing answers to your questions.

Expand Down

0 comments on commit c72ed70

Please sign in to comment.