Document first

It is a consensus in the software development community that documentation is essential. But at the same time, it's not one of the most glamorous tasks, especially compared to writing code. So it's natural for us developers to think:

What if I generate the documentation from the source code??

I've used this approach in a few projects, but in recent years I've taken a slightly different process, which I call "documentation first." I will illustrate with an example.

Imagine a team made up of a backend and a frontend developer. This team should implement the following task:

Develop the product registration form

At the time of refinement, I always suggest that the team could break this task into sub-tasks, such as:

• Define the API contract
• Develop the API
• Develop the form
• etc.

For the context of this post, only the first task is essential. In it, the team works together to define the API contract. They discuss data format, whether the API will be Rest or RPC, authentication, data compression, and other vital issues. The delivery of this task is the documentation, preferably in a standard like OpenAPI or API Blueprint (my preferred format).

With this task completed, they can now work in parallel again. The backend development will focus on delivering the API defined, while the frontend will implement the form knowing what it will send and receive from the backend. In addition, generating mocks and stubs is possible if they write the documentation using one of the abovementioned standards, making development and testing easier.

Of course, during the development process, the team may encounter some edge cases they didn't see during the documentation phase. When this happens, a quick rework is needed to adjust the documentation, and the work goes on as expected.

With this approach, I found some advantages such as:

• the team spends more time thinking about the scenarios in which the API will be applied, generating greater understanding before any line of code is written;
• there is an improvement in the rapport between team members;
• The documentation keeps up to date and alive.

I used an example of API development here. Still, the same approach can be applied in other scenarios, especially where we have integration between parts of the system, such as in a microservices environment.

As I mentioned earlier, I've been using this approach for the last few years, and the result has been very worthwhile. I hope it makes sense for your team and if so, use the comments to share your experiences.