So Your New Team Has Bad Documentation

Ariana Bray
7 min readFeb 5, 2020


Learn quickly, contribute early, and don’t get stuck fixing everything yourself.

A person writes in a notebook, adding items to a checklist
Photo by Glenn Carstens-Peters on Unsplash

First of all, who am I? I’m an entry-level, Black, female software engineer. I received my degree in Bioethics and Society from the University of Pennsylvania, then made a career switch into tech by attending Ada Developers Academy in Seattle. Some of my worries or concerns may not resonate with everyone who reads this article, but they are valid experiences that may feel familiar to a lot of people. The point is this: engineers of all types and at every level have a responsibility to contribute to documentation — both team-internal documentation and documentation for the users of their products.

Picture this: I’ve just started my first engineering job. I have my new machine, my potted plant (Josephine) is at home on my desk, and I’m finally ready to begin working. What better way to start than by walking through my team’s documentation? But… hold up. The documentation provided is confusing and out of date.

If you’re like me, not being able to work through documentation may unearth some uncomfortable feelings — frustration and our dear friend Imposter Syndrome among them. Maybe you’re worried that bringing up issues early will get you labeled as difficult. If you’re really like me, you aren’t going to let poor documentation get in the way of establishing yourself as an active, productive member of your team.

So, what do we do about it? We don’t have to suffer through the confusion of poor documentation just because everyone else has struggled. Here are some things I’ve learned that helped me turn the setback of poor documentation into an advantage that I use to contribute early and learn quickly.

Quick Tip: Hold On To Your Receipts. A tip that I’ve received from other womxn engineers is to always keep a record of my work. Oftentimes (and for myriad reasons), our accomplishments are overlooked or minimized. While I haven’t experienced this at Nordstrom, I have noticed it at other points in my career. I counteract that by making sure that every one of my work-specific tasks has a story, ticket, or some kind of permanent record.

Before You Even Touch The Documentation…

Transform your thinking! On my first day, I felt embarrassed and annoyed that I understood basically nothing about my team’s product (Was it a logical feeling? No. Did I feel it? Absolutely). As it turns out, having no context wasn’t a disadvantage after all. I was able to look at the existing documentation with fresh eyes. We all make assumptions. Whoever wrote the documentation made assumptions about a user’s base level of knowledge. I didn’t have this knowledge, so I was able to see areas for clarification and opportunities for an improved user experience.

Open Pandora’s Box — but take notes!

It’s going to be painful, but the first thing to do (after creating a record of what work is being done) is to work through the existing documentation. My manager gave me this task as part of my onboarding. Keeping a notebook and pencil nearby kept following the documentation from becoming an exercise in frustration. At each step, I made a note of problem areas.

What’s a problem area? A problem area can be an area where you (or a user) will second-guess or get stuck on what to do next. A problem area can also be an area with typos, grammar mistakes, or broken links. Is something in the documentation vague? Is the documentation out of date? Make a note of these things and move on. If the documentation is so poor that getting to the next step is impossible, note that too.

Don’t Go Too Far Down the Rabbit Hole (also titled Don’t Typecast Yourself)

Thorough documentation is rarely confined to one page. It’s tempting to follow every link, writing down things that should be improved. Documentation should absolutely be clarified, but taking on too much at once can be dangerous. If you’re not careful, you could end up spending the majority of your time fixing everyone else’s documentation. I know that I’m actively avoiding being pegged as the “documentation girl.” We are engineers. We’re here to write code (with accompanying documentation, of course). Rather than take all the problems on yourself, discuss setting a team standard for documentation. For example, the team could have a rule that states, “Any time a section of code is updated, its accompanying documentation must be updated before a merge request is approved.”

Be the Change

Bring up the solution while bringing up the issue. At the next team meeting or standup, speak up about your onboarding or documentation experience. I said something like, “I’ve been getting up to speed by reading the quick start documentation that we provide to our users, and I’ve noticed some difficult areas that can be updated or clarified. I want to take on that task.” That is more helpful than commenting, “This documentation is horrible and confusing, and I couldn’t figure out how to use the service. Please tell me what to do.”

Once you have ownership of your part of the solution, remember to document that work. If your team uses a Kanban board, create a story or stories that show what you’re working on. For example, “Update new team member onboarding documentation” or “Clean up external FAQs”.

It’s Dangerous To Go Alone

There’s a reason I didn’t start trying to solve the problem areas as soon as I found them. Maybe the problem areas were issues that I knew how to resolve — things such as grammar or typos. What happened more often, however, was that I needed a second (or third) pair of eyes to look at a problem area. When I nominated myself for some documentation cleanup, I added another sentence — “[Teammate], can I put some time on your calendar this week to walk through the existing documentation?”

Here’s a hidden benefit: I got a much deeper understanding of the team’s projects and products because I walked through documentation with a team member. A person who has been on the team for [more time than me] will have context that I’m missing. Instead of waiting weeks or months to acquire that context, boom! I have it now. My teammate also brought up problem areas that I didn’t encounter.

Because I noted my problem areas before putting time on someone’s calendar, the time I spent with my coworker was much more productive. When I walked through the documentation with my teammate, I brought up those areas: “Step 4 tells the user to do [XYZ], but it looks like they’ll need special permissions. How are those permissions granted? Does the user request them, or do we grant them ourselves?” Write down the solution for each issue. If follow-up with another team member is needed, note that too.

Break It Down

Bad documentation can seem like an insurmountable problem — where do you even begin fixing it? I approached the documentation the same way I approach most of my problems — by breaking it down into smaller pieces. Let’s say you’re fixing some documentation about how to run an application locally. Within the story you’ve created, create sub-tasks that break the larger issue down into smaller pieces. Remember to be aware of any assumptions you’re making about the reader of the documentation. Are they developers? Is it their first day too? Start at the beginning and create the smallest tasks you can. Here are some examples:

  1. For team-internal documentation, if your team prefers using a certain IDE or package manager, make sure that the documentation states that.
  2. For both internal and external documentation, if there are dependencies required to make an application or service run, list them (and link to or provide resources on how to install them).

Define Done

There will be times when poor documentation will take more than one sprint to fix. I’ve adopted a tip from my PM, Oz — I make sure that each story I create (documentation or otherwise) has a Definition of Done (DOD). Having a DOD makes me certain that I’ve ended my documentation cleanup in a logical place. My primary career goal at this moment is to learn and to push code. I’m always picking up tasks on new projects. As much as I believe that fixing documentation is important, I don’t devote 40 hours a week to only that.

Example story with tasks and Definition of Done (DOD)

Get a Proofreader (also titled Two, or Three, or Four Heads Are Better Than One)

Whenever I make documentation changes, I open a merge request and require at least one approver. I do this for two reasons.

Firstly, the team is reminded that documentation changes are coming. Someone else on the team has the chance to review the new documentation. They can catch opportunities for further clarity or spot any issues that I may have missed.

Secondly, opening a merge request is more confirmation that I was doing valuable work.

Share It!

Once the documentation has been updated, let people know! For example, you can send an email, highlight it in a meeting, or send a Slack message to your team or to any channels related to your project or product.

Be Open to Feedback

Once the updated documentation is shared, provide an avenue through which readers and users can suggest feedback. I work with a lot of data scientists. I need to know a fair amount about data science. I am not a data scientist. A data scientist might have different problem areas, and that’s okay. My goal is to add value by making documentation clearer — for everyone.

Thanks for reading along! These tips for handling documentation were compiled from personal experience and tips from friends and coworkers. If there’s anything you do to handle a poor documentation experience, let me know! After all, being open to feedback is an important step.



Ariana Bray

Ariana (she/her) is a software engineer. She has been an intern/full-time engineer at Nordstrom since August 2019.