Context

A context section should be the first section of the software documentation and simply used to set the scene for the remainder of the document.

Intent

A context section should answer the following types of questions:

  • What is this software project/product/system all about?
  • What is it that's being built?
  • How does it fit into the existing environment? (e.g. systems, business processes, etc)
  • Who is using it? (users, roles, actors, personas, etc)

Structure

The context section doesn't need to be long; a page or two is sufficient and a context diagram is a great way to tell most of the story.

Motivation

It's surprisingly common to see software documentation that doesn't start by setting the scene and, 30 pages in, you're still none the wiser as to why the software exists and where it fits into the existing IT environment. A context section doesn't take long to create but can be immensely useful, especially for those outside of the team.

Audience

Technical and non-technical people, inside and outside of the immediate software development team.

Required

Yes, all software documentation should include an initial context section to set the scene.