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 them. Developer experience 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. User experience (UX) 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 when 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 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 ( ) 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. C++, Node.js, Python, Git 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 in OS 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 . 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. versions of Windows 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 to manage my Node.js, but it’s not what you find when you go to the Node.js website to check for installation guides. nvm 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 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. using Docker How to deal with it . 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. Accept that it will take time . 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 I shared previously. Ask questions tips . Ultimately, try improving the experience for the next person who 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 quickly. 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. Improve the doc 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. Also published . here

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Navigating Onboarding Challenges For Existing Projects: A Dev's Perspective

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

3 Steps to Adding End-to-end Tests to Your Project

The Noonification: Go and Protocol Buffers (Quick Tutorial) (10/15/2023)

3 Tips for Effective Kubernetes Application Troubleshooting

3 Top Tools for Implementing Kubernetes Observability

53 Stories To Learn About Containerization

3 Steps to Adding End-to-end Tests to Your Project

The Noonification: Go and Protocol Buffers (Quick Tutorial) (10/15/2023)

3 Tips for Effective Kubernetes Application Troubleshooting

3 Top Tools for Implementing Kubernetes Observability

53 Stories To Learn About Containerization

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps