About Design Docs

#designdocs

This article was originally published on bmf-tech.com.

Overview

I researched about Design Docs.

Design Docs are documents for software design.

They do not have a fixed format and are written in a way that is meaningful to the project.

Design Docs have several benefits in the development process, such as:

Although there is no specific format, it is recommended to clarify the context, scope, goals, and non-goals of the design.

The length of the document should be short enough for busy people to read quickly.

Whether or not to write a Design Doc depends on whether the benefits of writing it outweigh the costs of maintaining it.

Design Docs have the following lifecycle:

Creation and iteration (re-editing the document)
Review
Implementation and iteration (updating the document)
Maintenance (updating the document) and learning (assisting system understanding for those who want to interact with the system)

Examples of Design Docs include:

It seems necessary to define and understand the form of documents that are valuable to the team or project
- Why write it (Why), who reads it (Who), how to write it (How)
- Especially if it's a design document or meeting minutes, it can be difficult for both the writer and reader if the document appears differently to different people
If you decide on a document format, there is a risk of thinking within that format and finding it difficult to think outside the box
- I feel that the purpose and understanding are more important than the format
Consideration of the operational cost of documents (review, updates, etc.) and whether it is worth paying that cost
- Like Mercari Shops, not updating might be an option. Or just updating when noticed
- Just like the system, the operational aspect needs to be properly considered
The lifecycle of Design Docs should be able to be integrated well into an agile development process
The form of operation may change depending on the viewing range, such as external publication (API documents) or internal publication
If you want to conduct a thorough review process, managing it as a repository on GitHub might be an option