Design Docs at Google post를 읽으며 필요한 부분을 정리하려고 합니다.

Design Document 란, 작성 이유?

chatGPT의 간략한 설명

Design document는 프로젝트에 참여하는 사람들 간의 커뮤니케이션을 위해 필요한 문서입니다. 비공식 문서이므로 엄격한 가이드라인을 따를 필요는 없습니다.

As software engineers our job is not to produce code per se, but rather to solve problems

소프트웨어 개발자로서 우리의 일은 코드 자체를 생산하는 것이 아니라, 문제를 해결하는 것입니다.

Design document의 기능

Besides the original documentation of a software design, design docs fulfill the following functions in the software development lifecycle:

• Early identification of design issues when making changes is still cheap.
• Achieving consensus around a design in the organization.
• Ensuring consideration of cross-cutting concerns.
• Scaling knowledge of senior engineers into the organization.
• Form the basis of an organizational memory around design decisions.
• Acts as a summary artifact in the technical portfolio of the software designer(s).

소프트웨어의 설계 원본 문서 외에도, 설계 문서는 소프트웨어 개발 lifecycle에서 다음과 같은 기능을 수행합니다.

• 설계 문제를 조기에 식별하는 것은 수정할 때 비용이 적게듭니다
• 조직에서 설계에 대한 합의를 달성합니다
• cross-cutting concern(공통 관심 사항)을 고려합니다
• 시니어 엔지니어의 지식을 조직으로 확장합니다
• 설계 결정을 중심으로 조직 기록의 기초를 형성합니다
• 소프트웨어 디자이너의 기술 포트폴리오에서 요약 아티팩트(?) 역할을 수행합니다

That is, given the context (facts), goals and non-goals (requirements), the design doc is the place to suggest solutions and show why a particular solution best satisfies those goals.

즉, 맥락(사실), 목표 및 비목표(요구사항)을 고려할 때, 설계 문서는 솔루션을 제안하고, 왜 특정 솔루션이 이러한 목표를 가장 잘 충족하는지 보여주는 장소입니다.

Design Document에는 어떤 내용이 들어있어야 할까?

System-context-diagram

In many docs a system-context-diagram can be very useful. Such a diagram shows the system as part of the larger technical landscape and allows readers to contextualize the new design given its environment that they are already familiar with.

많은 문서에서 system-context-diagram은 유용합니다. 이 diagram은 큰 기술환경의 일부로서의 시스템을 보여줍니다. 그리고 설계 문서를 읽는 사람들에게 이미 친숙한 환경에서 새로운 설계를 맥락화할 수(상황을 설명할 수) 있도록 도와줍니다.

APIs

If the system under design exposes an API, then sketching out that API is usually a good idea. In most cases, however, one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date. Instead focus on the parts that are relevant to the design and its trade-offs.

시스템 설계 중 API를 노출해야 할 경우, 해당 API를 개요로 스케치하는 것이 일반적으로 좋은 생각입니다. 그러나 대부분의 경우에는 공식적인 인터페이스나 데이터 정의를 문서에 복사하여 붙여넣는 것은 지양해야 합니다. 이러한 정의는 종종 장황하고 불필요한 세부 정보를 포함하며 빠르게 오래된 정보가 됩니다. 대신, 설계와 그 트레이드오프에 관련된 부분에 중점을 두세요.

Data storage

Systems that store data should likely discuss how and in what rough form this happens. Similar to the advice on APIs, and for the same reasons, copy-pasting complete schema definitions should be avoided. Instead focus on the parts that are relevant to the design and its trade-offs.

데이터를 저장하는 시스템의 경우, 이러한 데이터가 어떻게 어떤 대략적인 형태로 저장되는지에 대해 논의해야 합니다. API에 대한 조언과 유사하게, 전체 스키마 정의를 복사하여 붙여넣는 것은 지양해야 합니다. 대신, 설계와 그 트레이드오프에 관련된 부분에 중점을 두세요.

Code and pseudo-code

Design docs should rarely contain code, or pseudo-code except in situations where novel algorithms are described. As appropriate, link to prototypes that show the implementability of the design.

혁신적인 알고리즘이 설명되는 경우를 제외하고는, 설계 문서에 코드나 의사 코드를 포함시키는 것은 드물어야 합니다. 적절한 경우, 설계 구현 가능성을 보여주는 프로토타입에 링크를 걸어야 합니다.

Degree of constraint(제약 정도)

it also needs to quickly define a set of rules that allow zooming in on a manageable set of solutions.

관리 가능한 솔루션 집합으로 축소할 수 있는 규칙 집합을 빠르게 정의해야 합니다

Design Document의 길이는 어느정도로?

Design docs should be sufficiently detailed but short enough to actually be read by busy people. The sweet spot for a larger project seems to be around 10-20ish pages. If you get way beyond that, it might make sense to split up the problem into more manageable sub problems. It should also be noted that it is absolutely possible to write a 1-3 page “mini design doc”. This is especially helpful for incremental improvements or sub tasks in an agile project–you still do all the same steps as for a longer doc, just keep things more terse and focused on a limited problem set.

설계 문서는 충분히 자세하면서도 바쁜 사람들이 실제로 읽을 수 있을 만큼 짧아야 합니다. 대형 프로젝트에 대한 최적의 분량은 대략 10-20 페이지 정도입니다. 그 이상이 되면 더 관리 가능한 하위 문제로 분할하는 것이 좋을 수 있습니다. 또한, 1-3 페이지의 "미니 설계 문서"를 작성하는 것도 가능합니다. 이는 점진적인 개선 또는 애자일 프로젝트의 하위 작업에 특히 도움이 됩니다. 여전히 더 긴 문서와 같은 단계를 수행하지만, 문제 집합을 한정적으로 유지하고 간결하게 유지합니다.

마치며

저희 파트에서도 Design document를 작성하려고 합니다.
실제 작성해보며 느낀 점들 혹은 고려해야 할 사항이 생기면 포스팅 하겠습니다.
읽어주셔서 감사합니다.