Developing the "onboarding" process for a new person in an engineering team takes a lot of dedication, and keeping this process fluid takes even more work (with as little friction as possible).
This issue is challenging for any team working full time, it is even worse for Open Source projects where contributors usually work in their spare time. We should make this process as fluid as possible so that people don't get discouraged by the complexity of getting up there and testing, until they make their first pull request.
Configure development environment
Every developer has a different way of setting up a development environment, even if it is in a popular technology (programming language) with lots of documentation, text editor extensions (emacs, vim, vscode, ...), etc.
We developers are used to “our way” of doing things, it is common for us to create resistance when someone presents a different way and I do it another way.
In the vast majority of applications they depend on external resources such as databases, APIs, tokens, etc., if we force the developer (user) to read all the project documentation before having the first contact with the project it is very likely that we will lose his engagement, and some frustrations in him, such as:
- I just wanted to test
- I have to read all this to see it working
- What a complicated project
- I have to install X, Y and Z services/software on my machine
- I don't know the programming language used in the project, which plugins should I install in my editor?
- ... and much more.
There are some tools to assist project maintainers (open source or private) to generate an onboarding process with as little friction as possible.
Configuring editor (with all the necessary plugins and parameters), all the services the project needs to run, environment variables configured, database running with initial data load, data viewer configured (software to manage data from the database), etc.
To the point where the developer “clicks a button” and magically has the development environment ready to test the software.
In the last few months we at prestd have been working on improving our documentation (it is far from being good documentation) and removing as much friction as possible in the process of getting a new development environment up, some issues we have implemented until we got to what we have today:
-
Improve local tests execution — it is frustrating that someone wants to contribute and cannot run the local tests (we use e2e tests, making requests to prestd's own API), a way was implemented where the tests run inside docker using
docker-compose; - Documentation: new content architecture — thinking of a person who has never had contact with prestd and wants to test or use it in a production environment, both people should get into the documentation and be able to do what they want to do (bring up the environment);
- Onboarding of new contributor: using devcontainer — prepare the development environment with "1 click" using devcontainers (GitHub Codespaces support).
See prestd's development guide page here.
It is not nice to have the engineering team working in a bad environment, we need to think more about our team and make the team experience fluid.
people > technology
Focus on the developer (user)
The prestd exists open source since 2016, I particularly like the project very much and believe it is a great solution to accelerate the development of a RESTful API for existing database and especially development of a new API (project starting from scratch).
But for many years we turned to developing the software didn't look at documentation with the dedication we should, causing the contributor base to shrink (existing and new) — people going through open source project, hardly stayed for many years, so we always have to have the most rounded onboarding process possible.
Given this problem I started to look at the documentation with more dedication and every decision in prestd from now on will be thinking about the developer (user) experience, answering the following questions:
- Will this improve the developer experience using the project?
- Will this make the project easier to use?
- Will this make it easier to maintain the development of the project?
When all 3 questions are “yes”, we will proceed with the implementation, regardless of what it is: feature, improvement, fix, etc.
Top comments (0)