TL;DR 오히려 정보를 덜어내는 것이 효과적일 수 있다.
서론
다이어그램은 협업을 위해 명세서를 시각화한 도표이다. 즉 효과적인 이해와 의사소통을 위해 작성하는 문서이다. 따라서 많은 정보를 담고 있을수록, 이해가 어려워지며 설명하는 사람도, 이해하는 사람도 서로 힘들어질 수 있다.
따라서 잘 읽히는 다이어그램을 작성하기 위해 고민했던 내용들을 공유해보고자 한다.
다이어그램 선정
먼저 필요한 상황에 맞게 다이어그램을 선택해야한다.
UML 2.5 Diagram 기준으로 존재하는 다이어그램은 다음과 같다.
(https://www.uml-diagrams.org/uml-25-diagrams.html)
CI/CD 환경을 설계할 때에는 배포 다이어그램을 작성하거나, 사용자의 관점을 표현하고 싶다면 유스케이스 다이어그램을 작성하는 등의 선택을 할 수 있다.
이번에 내가 고민한건 요구사항에 대한 흐름도 설계를 그려내는 과정이였기에 시퀀스 다이어그램을 작성해 표현해보겠다.
시퀀스 다이어그램이란
정의
Sequence diagram is the most common kind of interaction diagram, which focuses on the message interchange between a number of lifelines.
(https://www.uml-diagrams.org/sequence-diagrams.html)
직역해보면 시퀀스 다이어그램은 가장 일반적인 형태의 상호작용 다이어그램이며, 여러 생명선들이 서로 주고받는 메시지를 중심으로 보여준다고 한다.
즉 상호작용을 표현하기 위한 도표이다.
효과적인 표현 방법
시퀀스 다이어그램의 모든 구성요소를 작성하지 않아도 된다. 필요한 상황에 맞게 변형해도 된다. 그저 목적인 "효과적인 의사소통/이해/협업"에 집중할 수 있도록 표현하면 된다.
예시로 토스페이먼츠의 결제연동 가이드의 시퀀스 다이어그램을 보자.
슥 읽혀서 놓칠 수 있지만, 디테일하게 보면 다음과 같은 부분을 눈치챌 수 있다.
1. 인증에 대한 내용이 없다.
2. 결제 실패에 대한 내용이 없다.
이 시퀀스 다이어그램은 연동을 원하는 개발자의 입장에서 작성된 문서이기에, 인증은 토스페이먼츠 내부의 역할이고, 결제 실패에 대한 처리도 토스페이먼츠 내부의 역할이다. 연동을 원하는 개발자는 토스페이먼츠의 API 스펙과 동작에 집중해야 하지 내부적인 처리 방법까지 이해할 필요가 없다고 판단해 상당한 정보를 생략한 걸 볼 수 있다.
이런 디테일한 부분 때문인지, 연동하는 개발자의 입장에서는 필요한 부분만 빠르게 파악하고 작업에 들어갈 수 있다.
어쩌면 생략이 도움이 될 수 있다는걸 알 수 있는 지점인 것 같다.
추상화의 단계
시퀀스 다이어그램을 작성하다보면, 요소들이 많아져 스케일이 커질 때가 있다.
이럴 때에는 추상화의 단계를 높여 분리를 해보는걸 추천한다. 컨트롤러, 서비스같이 레이어드 아키텍처 단위가 아니라, 주문/제품/재고/결제 같은 도메인 단위로 나눠보는 것이다.
예시로 주문 생성 API를 설계하고 방향성에 대해 평가받아야 되는 상황이라고 가정해보자.
Order, Product, Stock, Payment등 다양한 레이어드 아키텍처들이 상호작용 과정을 표현하고 있다. 그리고 호출되는 메서드들과, 쿼리를 담아내며 디테일하게 설명하고 있다.
하지만 이 정보가 과연 효과적인 의사소통을 하는데 도움이 될 지는 잘 모르겠다.
만약 디테일한 로직 설명이 필요하다면 별도의 시퀀스 다이어그램으로 분리해 디테일한 정보가 필요한 사람에게 보여주면 되는 것 아닌가? 이런 생각을 했다.
그래서 핵심적인 부분만 담고 요소들이 많으니 파악하기 어렵다고 느껴져 도메인 단위로 분리해 다이어그램을 다시 그려봤다.
이제는 읽히지 않는가? 유저가 주문 요청을 하면 상품 조회와 차감이 이뤄지고, 결제를 요청해 마무리하는 플로우가 한눈에 들어온다. 추상화 레벨을 도메인 단위로 올려 효과적으로 이해할 수 있도록 한 것이다.
만약 개발자 혹은 그외 다른 직업을 가진 사람들과 의사소통이 필요할 때에는 대화 주제, 상황에 알맞게 추상화 레벨을 높이고, 정보를 생략하며 조율한다면 앞서 말한 잘 읽히는 다이어그램으로써 작동할 것이다.
추상화 - 주의해야할 점
이때 주의할 점은 추상화 단계를 올린만큼 다른 요소들의 단계도 같이 올려서 일관성을 맞춰야한다. 도메인 단위로 추상화 단계를 올렸지만, 서비스와 레포지토리가 등장한다면 읽는 사람의 입장에서는 의문을 가질 수 있다.
위 예시와 같이 주문 도메인에서 갑자기 레포와 DB, 외부PG등 추상화 단계가 맞지 않는다면 이해를 위해 추가적인 시간이 요소되기 때문이다.
마무리하며
처음에는 디테일한 정보를 모두 다 담아두면, 좋은 것 아닌가? 라는 막연한 생각을 가졌지만 읽는 사람의 입장을 생각했을 때 이해하지 못한다면 공을 들여서 쓴 문서는 이면지와 다름 없겠구나 같은 생각을 했던 것 같다.
회의나 API 연동 문서 등 상황에 맞게 정보 생략과 추상화의 레벨을 맞춘다면 가독성이 훨신 좋아질 수 있으니, 다이어그램 작성 전 누가 읽는 것인지 고민을 해보는 걸 추천한다.
참고사이트
https://www.uml-diagrams.org/uml-25-diagrams.html
https://docs.tosspayments.com/guides/v2/payment-window/integration
https://wikidocs.net/220975
