Development environment documentation

Jamie Templeton

A software development team needs ‘development environment set-up guide’ documentation. A good team keeps it short.

Write a development environment set-up guide

Whatever software development method you use, a product development team needs a written guide to setting up a development environment for a new team member. A new team member needs step-by-step instructions for getting the source code, running tests, building the application, and running the application on a new workstation.

You can explain anything verbally, without documentation, but in practice no-one memorises every detail: URLs, file paths, customisable settings and the like. Writing these details down makes life easier.

Ideally, you minimise the required set-up by automating the development environment, and the build in particular. However, even if you do this, you still need to know how to get the source code and run that build, as well as perform other tasks. Besides, you probably didn’t actually automate everything.

Write documentation for new team members

In theory, a development team might not need any documentation: they know how to build and release software, and plan development using user stories. Of course, in theory the team never changes either.

In practice, team members will come and go. A short-term project may start and finish with the same team, but software tends to get extended, and someone else will have to pick-up maintenance or further development later on. Alternatively, during long-term product development, if each developer stays on the team for a year you’ll end up with a team member rotation every couple of months.

Changing the development team disrupts development: time spent on handover, and differences between developers, breaks velocity calculations. As well as reducing productivity, this makes estimates less reliable and reduces predictability. To some degree, you can address this with documentation.

Save time and spread team rotation cost

You get two benefits from writing documentation for new team members to use during their first weeks on the team:

1. save time - it takes less time to write development environment documentation than to figure it out
2. spread the cost of team member changes - reduce the impact on existing team members.

Documenting a development environment requires less skill than, say, capturing product requirements in writing, so this doesn’t take long. Figuring it out without documentation takes a lot longer.

Without documentation, not only does a new team member takes longer to get up and running: an existing team member has to spend time helping them. Team members can write documentation in slack time on previous sprints.

Put it in the README

However little documentation software developers tell you they need for themselves, they at least need a README to bootstrap new team members’ knowledge. Include development environment documentation in that README.