Often, when you start working on a project, you will find yourself struggling with the most basic task: getting it up and running on your machine. This can be a frustrating process, so let’s see what causes those problems and how you can handle it.

Developer experience

User experience (UX) focuses on how the user interacts with the system and makes their journey as smooth as possible. Similarly, we could consider developer experience with the system. Usually, in small projects, the priority of improvements that benefit developers is low enough to never be done.

The examples of good developer experience come from large projects and products targeting developers specifically—for example:

• Cypress for end-to-end testing,
• popular frameworks, such as Angular or React, or
• GitHub, CircleCI, etc.

Small companies, or one-person open-source projects, often lack the resources needed to make your journey pleasant. Simply, if you have to onboard a new developer once a year, it can be cheaper to have them struggle for a bit then to make the installation smooth.

Ever-growing complexity

Projects tend to grow in complexity with time. All the time, things are being added:

• new features
• refactorings that take forever to be applied on the whole codebase
• dependencies that become outdated

If you have a project that lasts for a few years, it will definitely be more complicated than something that would be written now.

The accumulated complexity often spills into troubles with starting up the project: you might find a mismatch of technologies, and they can interact in an unexpected way when you start the project on a new machine.

Documentation challenge

Explaining things in writing can be difficult, but this doesn’t often receive enough attention. Even if the team you join tries to keep docs of a decent quality, there is always one challenge left: they have to assume some level of knowledge in the reader. There is always a trade-off involved with that—when you explain too much, it will be more work to write and maintain the docs. Moreover, you could flood the reader with too much text. If you explain too little, the documentation will lack crucial information for some people.

Some common examples of things you could struggle with:

• Plenty of programming (C++, Node.js, Python, Git) and internet tools (Apache, Nginx) come from Unix-based systems—if your background is in Windows, then you will be struggling with some underlying concepts.
• Many programming tools are built with the command line interface (CLI) in mind: the most important is Git, but other tools are often important as well—ESLint, Prettier, etc. If you have never used CLI tools, you might have gaps in knowledge that no project documentation will try to address.

When I was starting to learn programming, I often got stuck on one or two sentences of the book that described a step I couldn’t overcome. Luckily, as time goes on and you gain experience, cases like this become less common.

Unexpected differences

There can be many differences between your machine and whoever builds the system you’re trying to start now.

Differences in operating systems tend to cause the biggest issues. Linux's distros and macOS are usually compatible enough to be considered one camp. On the other side, we have different versions of Windows. If you join a project that was built on an operating system very different from yours, then you are likely to discover some incompatibles that nobody expected. In JS projects, it’s often expected to be able to run it on whatever OS you like, but it can require some effort to make it truly compatible between systems.

Another surprise can come with the ways of installing tools you need to run the project. For example, last time I checked, Windows had three ways of installing Git—each method doing things slightly differently. Similarly, Node.js or Python can be installed in many ways on Unix systems, and sometimes developers forget about the ways that are different from their preferred one. I always use nvm to manage my Node.js, but it’s not what you find when you go to Node.js website to check for installation guides.

Containers to the rescue?

Containerization, which was made popular with Docker, makes it simpler to move across machines and OSes. Unfortunately, you would still be lucky to have your whole developer journey paved with well-prepared, ready to use images. At my job, I had a good experience using Docker as a shortcut to getting a backend up and running quickly locally. Nonetheless, I still struggle to move the whole developer experience to containers so that everybody has the same dependencies available. Containers are a great tool, but any work at optimizing developer experience faces the same lower priority that we mentioned earlier.

How to deal with it

Accept that it will take time. If your team tells you that the setup can be tricky, or that you can expect some issues—trust them, and don’t get frustrated.

Ask questions. I’ve seen more devs erring on the side of asking too few questions or too late rather than asking too many or too early. If you don’t want to be annoying, or just want to be somehow independent, set an alarm clock to add an hour or two and ask a question when it rings if you are still stuck. Then you can take your time to describe your issue well, following the tips I shared previously.

Improve the doc. Ultimately, try improving the experience for the next person that will take the same path. The places where you struggled are valuable indicators of where the docs are lacking. Maybe “install Node.js” needs more elaboration with respect to “from where” and “how.” Perhaps you are the first one to run the project on Windows, so you could help others take the same path quicker. In a way, during your installation, you become a beta tester of the documentation, and with everything running, you have enough experience to improve the docs.

What was your experience with getting onboarded on a project?

Please share in the comments—I’m truly interested in hearing how it goes for newcomers to projects.