Scrum project documentation - development
environment set-up :tags: [scrum,methodology]
A software development team needs ‘development environment set-up guide’ documentation; if they’re good it’ll be short.
Documentation for new team members
In theory, a Scrum project 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 reality, Software development teams change; people come and go. In some commercial environments, where teams have more independent contractors than permanent employees, team members last as long as burger chain employees. 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 maintenance or further development later on. Alternatively, on a long-term project, if each developer stays on the project for a year you’ll still end up with a team member rotation every couple of months - once every few sprints.
Changing the development team disrupts a Scrum project. Time spent on handover and differences between developers break velocity calculations. As well as reducing productivity, this makes estimates less reliable and reduces predictability. To some degree, you can address this with documentation.
Benefits of writing for new team members
There are two reasons to write documentation for new team members to use on their first sprint:
-
to save time - it takes less time to write precise instructions than to figure it out
-
to spread the cost of team member changes - to reduce the team change’s impact on existing team members.
Unlike software requirements, say, a development environment is easy to document, so this doesn’t take very long. Figuring it out without documentation, on the other hand, takes a lot longer.
Without documentation, not only does a new team member take longer to get up and running: an existing team member has to spend time helping them. Writing documentation allows you to spread the cost - team members can have written it during slack time on earlier sprints.
Development environment set-up guide
Whatever software development method you use, a development project needs a written guide that a new team member can use to set up a development environment. 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.
Without documentation* you can explain these things verbally, but in practice there are details that no-one memorises: URLs, file paths, customisable settings and the like. It’s just easier to write these things down.
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 really automate everything.
In practice you have at least the following steps:
-
Get source code (e.g. clone a git repository)
-
Install pre-requisites (e.g. JDK, build tool, database, server)
-
Build/run the application (i.e. run the build tool)
Even if you only have these three steps, you still need more detail. What are the pre-requisites, exactly, and which versions do you need? What’s the source code URL? Which build tool 'command' should you use? The best way to answer these questions is to quote the exact command lines, which are beautifully unambiguous. And if you can’t do each of these with a single command, then you either need to break it down into more steps, each with their own commands, or automate it more.
-
Note: when we say ‘documentation’ we’re not talking about word-processors and paper - we mean a project wiki. Obviously.