The First Step Towards Making Your Django Project More Onboarding-Friendly

Does the thought of setting up a new development environment for your Django project seem like a tedious task? How about helping somebody else to start helping with the development? Do you feel like you and your project would be well prepared?

If both of these scenarios sound uncomfortable, this article is for you. Read onto learn an easy first step towards making your project more onboarding-friendly.

Write a Friendly Note to Future-You

It doesn’t need to be a huge effort. Even a rough overview can be pretty useful.

Keep it brief, friendly and casual. No need to be too critical, or overthink it. What you’re writing doesn’t need to be flawless and complete on the first try.

Add a new section to your README, titled “Setting up a development environment”.

Start writing down the steps which come to mind, starting with cloning the project’s Git repository. What needs to happen so you can get a development server running?

What information is missing from the rest of your project? What language version was used? Are you using tools where it’s important to use a certain version? Jot those down, but it’s okay if you should miss something on the first go.

Here’s an example for getting started:

## Setting up a development environment

You'll need Python 3.6 and pip to install requirements pinned in requirements.txt.

* Clone this repository (use `git clone ...`)

Try To Follow Your Own Instructions

Not when they are complete, but while you are writing them down.

Start with step one - create a fresh clone of the Git repository, and continue with the next step. If you notice something is missing, add it to the list of steps. Either to the end, or at the place where it should have been done.

Here’s an approximate example of steps from one of my early-stage projects:

## Setting up a development environment

* Clone this repository
* Add a remote to the staging server `git remote add staging servername:reponame`
* `pipenv install --dev` to get dev packages
* create an .env file and add `DATABASE_URL=sqlite:///db.sqlite`
* Run `python manage.py migrate`
* Run `python manage.py createsuperuser`
* Run `python manage.py runserver`
* Navigate to http://localhost:8000 in your browser, the page should load
* In the admin, change site domain to "localhost:8000"
* The development server is good to go! Happy coding :)

I don’t expect that anybody except myself will read this anytime soon. Still, writing those steps down was well worth it already at this point. Sometimes, I link to relevant articles which provide an overview on getting started, or as explanation about certain steps. You don’t need to come up with everything yourself.

This Doesn’t Need To Be Perfect

Think of this, as a friendly note to a future-you. Not meant to impress anybody, but to provide a rough overview of the most important steps.

Sure, you could automate some of this. You probably will. Eventually.

Don’t let better be the enemy of good.

You will miss something. Writing this down will save more time than it will cost, even if you account for a lack of details. The setup will change, but if you keep this section light it won’t be much of an effort to fix it when the time comes.

More Helpful Information

Drafting up the steps needed to set up the environment is cool. You can add more subsections if you want. Whatever you think might help you in the future. Maybe a complex command, or a useful workflow to get started:

## Loading fresh data

* Download initial data from (...)

### Useful development commands

* pipenv run python manage.py makemigrations
* pipenv run python manage.py migrate

In Conclusion

Making it easier to set up a development environment doesn’t need to be a completely automated solution right away. You don’t need to go from 0 to 1 in one leap. It’s okay to start small and iterate from there.

Writing down a few notes about setting up the development environment is a great first step to make your Django project more onboarding-friendly.

It also helps to become more conscious of the development setup process.

Keep it brief and don’t put too much effort into it. You’ll want to automate lots of those steps eventually, and your process will probably change.

It’s not about perfection. It’s about the time you can save for you and your teammates in the days and weeks to come. It’s about how much easier it will be to start automating the most elaborate and annoying workflows later on.

If you’re working on a project, and don’t have a few friendly sections about setting up a fresh development environment you can start today. It’s not a big thing. It doesn’t need to be impeccable. You don’t need to learn a new tool before getting started.

Once you’re at it, why not add a few notes about performing frequent and useful development workflows as well?

In any case - start today. You will be happy you did.