Scrum software project documentation environment set-up

06 August 2012

Peter Hilton

by Peter Hilton

A Scrum development team doesn’t (necessarily) need any documentation, but there are usually other stakeholders who do.

Scrum is concerned with getting working software built. Like other agile software development methods, Scrum prioritises ‘working software’ over ‘comprehensive documentation’. Despite what many Scrum teams think, this is not a guideline to write no documentation at all. So how much documentation should a Scrum project produce?

Documenting the path to working code

If you look back to life before Scrum, it was common to write all kinds of documentation - things like project plans, requirements specifications, functional designs, technical architectures and test plans. These were the ‘artifacts’ that other software development methods defined, as part of some process that results in working code.

The only documentation that members of a Scrum team definitely need, to produce working software, is the product backlog. Scrum deliberately shortens the feature specification cycle into user stories, conversations with the product owner, code, test and demo - all within days rather than months.

Additional developer documentation

The product backlog is not the whole story, however. Although developers can get the information they need from the Product Owner or the source code, there are several kinds of documentation that a Scrum team may find useful, and which might make them more productive.

Functional documentation Technical documentation
  • Non-functional requirements 

  • Data model and data dictionary

  • Front-end design

  • User-interface map

  • External interface specifications

  • Architectural overview diagram 

  • Component diagram or inventory

  • Release/deployment guide

  • DTAP environment configurations

  • Operational/usage guide

This reads like the documentation set from an old-school heavy-process project, so what’s going on here? The difference is the level of detail.

In agile software development, it is always useful to challenge how much time you spend on activities that do not directly lead to working software; writing code, for example. For documentation, this means asking how many pages we’re talking about, and pushing back when people suggest the detailed documentation of the past. It’s unlikely that ‘none’ is the correct number of pages; one or two pages for each can be much more useful.

Another difference comes from thinking about priority. A classic data management application probably doesn’t need much in the way of front-end or UI documentation, but does need a data dictionary that explains what everything means. On any given project, maybe half of the documents mentioned above aren’t worth writing, while one or two are essential.

In the end, a productive and stable Scrum development team already knows all of this stuff, and doesn’t need to have it written down. So who does?

Other stakeholders

A notional ‘productive Scrum development team’ is all very well, but there are other stakeholders.

The most immediate stakeholder is a new development team member, especially if the team changes often enough that there is always a team member who has only done a few sprints with the team. Wishful thinking aside, handover and knowledge-transfer require more than a couple of hours in a meeting room and being dumped in at the deep end. It makes a big difference if a new team member can refer to basic instructions on setting up a development environment, understanding the functional and architectural big picture, and definitions of the project’s jargon and data model.

Other stakeholders, such as business sponsors, end users and marketing staff, need documentation like:

  • project vision and goals

  • project risk register

  • release schedule

  • functional overview

  • marketing brochure.

These are kinds of documentation that stakeholders outside the team need, which are part of traditional documentation sets. Team members inevitably have responsibilities other than completing user stories, and this is one of them.