Thomas Chavakis

Documentation Before Development

Introduction

Documentation Before Development (DBD), is an agile way of working within a software development team.

Every agile team in the software industry has to release products quickly and frequently, and usually documents the processes followed at the very end of the project.

The DBD process was created to address the problems arising when software teams start the delopment phase without analyzing in depth what is going to be delivered.

In this process you have to document the technical implementation of each task after the grooming meeting. The document will be under review from other team members until all technical details are clear and acceptable to everyone.

This technique is supplementary of the Architecture Decision Records ADR.

When

Before the end of each sprint, and after you have successfully delivered the tasks of the sprint, you have to make a preparation for the next one. Grooming meeting is part of this process.

The output of a Grooming meeting is that the team will have the chance to adjust the business need and provide a high-level point estimation. As a result, the Product Owner of the team will refine the backlog according to the team’s dynamics, such as the velocity of the team.

After the grooming meeting, the team can take the time to analyze each task of the next sprint and write a technical specification that will become a product of continuous collaboration with other team members.

The assignee will present the technical specification to other team members during the HOW meeting. Later on, all the domains/crafts will be based on this document for the development phase.

ddd

How

Step 1: Analyze the task at the Grooming Meeting

Step 2: Assign the Task to a team member

Step 3: Create a new Folder at the docs/dspec/ticket_number

Step 4: The assignee will generate a new MarkDown Document (readme.md) like this one:

docs/dspec/ticket_number/pb-13222/readme.md

Step 5: The assignee will complete the technical analysis document according to the template.

Step 6: Create a new Code Review

Step 7: The proposal is under review from all reviewers.

Step 8: When this code review is approved, you can merge it and start the coding/development phase.

Advantages

  • All team members contribute actively to technical decision-making through interactive reviews. In that way, everyone has a clear understanding of the expected final outcome.
  • You link the Business Need with the Technical Implementation with the Ticket. This could be used as reference for other teams with the same business need.
  • You think before start coding. There are fewer possibilities to follow the wrong path.
  • A possible project handover will be easier because process knowledge is not lost.This also facilitates new employees’ onboarding process.
  • This document is the “contract” which details all the agreed technical implementation and will become the source of truth for other crafts/domains who work in parallel with your team.
  • Sprint Cohesion and continuous development

Disadvantages

  • It’s a more time-consuming method

Template

The template can be different among teams, because each team has very different structure and business operation. An example will be the following:

## Ticket Link

## Problem 
Describe the problem or business need.

## Proposed Solution
Describe the solution and the technical approach to the problem.

### Artifacts
Import the Diagram that justifies the solution.

### Endpoint(s)
Analyze the possible endpoint request structure with the relative payload and method. 
Analyze all the success and error response(s).

### Database Changes
Write down all the possible changes to the database 

### Event Message Payload
Analyze the possible event message at the relative topic. 

## Affected Components/Services
Describe all the affected components or other microservices that will be impacted by this solution.

## Attention needed
Recognize possible code refactorings or important things that should be communicated before the implementation. This will help the code reviewers.

## Next Steps/ Improvements
Write down the possible improvements and the remaining work.