Starting from a Bad Onboarding Experience

Initial Preparations#

When you join a new company as a senior engineer, what’s the first thing you do?

If you’re in-house, maybe it’s setting up your favorite cup and keyboard. But no matter where you work, your real first task is usually setting up your development environment.

That setup might involve familiar or unfamiliar operating systems and programming languages. In such blind exploration, clear documentation is gold.

Evaluating Documentation#

When you open the onboarding doc, what do you notice first?
The logical order of the sections—or the environment requirements?

I tend to start with the logical flow.

If the headings look inconsistent, it might mean the author doesn’t have a clear idea of how to guide the reader. Or worse—just wrote whatever came to mind. Maybe the team doesn’t have a habit of reviewing documentation; otherwise, there would be at least basic fixes, like arranging headings from H1 to H3 properly.

To me, that’s a red flag.

Why? Because while the people writing these docs aren’t always senior engineers, they’re usually trusted domain experts. If they don’t care about their readers, there’s a risk they won’t care much about future collaboration either.

If the team accepts this, no matter how good the manager or members are, it creates variables that can complicate future work.

Sure enough, I hit my first roadblock: installing Docker.

As a frontend engineer, it struck me as odd to set up the backend locally when we already had an internal dev environment separating frontend and backend. But as a new hire, I wondered if I’d missed something. So I gave myself two hours to troubleshoot, updating the doc as I went, and kept my engineering manager—R, who later became my long-term manager—in the loop.

After I finally got it working, I got a message:
Most frontend engineers no longer set up the backend locally—the documentation was outdated.

How Would You React?#

Faced with that, what would you do?

• Shrug and move on because your environment is already ready?
• Mentally mark 👎 for the onboarding process?
• Or think, “This onboarding process sucks, but I’ll fix it”?

I chose the last one—probably because I’m stubborn.

Why else would this onboarding feel even more cumbersome than my previous job? Back then, local backend setup was actually necessary due to specific tech choices.

With two more years of experience, feeling stuck again made me dissatisfied—both with the team and with myself.

Taking Initiative#

Even though my main role was product development, I suggested using some spare time to revise the documentation—making it readable, usable, free of redundancy, and without dependencies scattered across multiple docs.

I didn’t know this small proposal would set the foundation for the next four years.

I sent R a basic plan. He replied with questions about readability issues and expectations for future documentation.
That’s when I learned: to get buy-in, you have to clearly explain the reasoning. I updated my proposal, added background, and explained the logic behind the new structure.

Once it was approved, I updated the docs and went back to my normal work.

After the Onboarding#

Five months later, before a new teammate joined, R asked me to make sure the setup docs were still up to date. I invited a few colleagues to review them. They casually pointed out that the project structure and coding guidelines were also outdated—and asked if I could refresh those too.

Would you take that on?

I did. Because it was a chance to uncover more issues worth discussing.
These topics came straight from our daily frustrations.

Each time I updated a document, I drafted a proposal, collected feedback, refined it, and made sure every team member explicitly approved before marking it “done.”

Only later did I realize: fixing uncertainty had quietly become my unique strength in the team.

At the time? I was just fixing what bothered me.