안녕하세요. ABC Studio에서 Delivery 기획을 담당하고 있는 이하림입니다.

ABC Delivery 팀은 현재 일본의 최대 규모 배달 서비스 '데마에칸(Demaecan, 出前館)'에서 배달원에게 배달 업무를 제공하고 고객에게 따뜻한 음식을 전달하는 배달 과정 전반을 담당하고 있습니다.

데마에칸은 일본에서 제공하는 배달 서비스이다 보니 한국과는 다른 일본의 배달 문화가 많이 녹아 있는데요. 예를 들어 일본은 현금 결제 비율이 높고 음식을 직접 수령하는 경우가 많아 고객이 집에 없는 경우 어떻게 대응해야 하는지도 프로세스에 반영돼 있습니다. 또한 아파트가 많은 한국과 다르게 일본은 개인 주택과 맨션 등 다양한 형태의 집이 있고 그에 따라 주소 체계도 다르기 때문에 찾아가는 방법을 공유하는 공간도 배달원 앱에 마련돼 있답니다.

이렇게 서로 다른 문화를 이해하면서, 또한 일본어와 한국어라는 서로 다른 언어로 소통하며 함께 고민하고 서비스를 발전시켜 나가기 위해 저희 팀에서 조금 더 신경 쓰는 부분들이 있습니다. 그중 하나가 바로 문서화인데요. 이번 글에서는 보이지 않는 배차 로직을 읽을 수 있는 문서로 담아내는 과정에서 했던 고민들을 나눠 보려고 합니다.

Engine은 말이죠!

데마에칸에서는 주문하는 고객과 조리하는 가맹점, 그리고 배달하는 배달원까지 세 분류의 주요 사용자를 중심으로 시스템을 만들고 있습니다. 그중 Delivery 파트에서는 배달원을 위한 서비스를 만들고 있는데요. 'Engine'은 Delivery 파트에서 운영하고 있는 다양한 시스템 중 하나로, 배달원에게 일을 할당해서 물품이 고객에게 전달되기까지의 모든 배달 과정을 담당하고 있습니다.

다음은 고객이 고객용 앱(Consumer)에서 주문을 실행했을 때 배달 과정에서 Engine이 어떤 역할을 담당하고 있는지 나타낸 그림입니다(Merchant는 가맹점용 앱, Driver App은 배달원용 앱, Controller는 관리자용 앱입니다).

위 그림을 보면 배달 과정에는 사용자의 눈에 보이는 영역(Visible Flow)과 보이지 않는 영역(Invisible Flow)이 있는데요. Engine은 보이지 않는 영역에서 크게 아래 세 가지를 중점적으로 담당하고 있습니다.

ETA
ETA는 'Estimated Time of Arrival'(도착 예정 시간)의 약자입니다. 주문하기 전에는 고객에게 배달을 받기까지 어느 정도의 시간이 필요할지 알려주고, 주문한 후에는 정확히 언제 상품을 받을 수 있는지 알려줍니다.
배차
효율적인 배차는 배달원에게는 수익으로, 데마에칸에게는 비용으로 연결되는 아주 중요한 요소입니다. 최적의 동선으로 음식이 준비 완료되는 시간에 맞춰 배차해서 배달원이 매장 내 대기 시간을 줄일 수 있도록 가장 좋은 오퍼를 배달원에게 제안합니다.
모니터링 및 배달 정보 제공
배달원이 배달 중일 때에는 배달을 어느 상태까지 수행했는지, 현재 어떤 위치에 있는지 모니터링해서 가맹점과 고객에게 안내할 수 있는 정보를 제공합니다. 이외에도 다양한 이슈 상황에 대응할 수 있도록 지속해서 시스템 기반을 넓혀가며 개선하고 있습니다.

왜! 정책서가 필요했을까?

Engine 소개를 보면 알 수 있듯 배달 과정에서 우리가 눈으로 확인할 수 있는 사항은 아주 적은 부분뿐입니다. 무슨 말인가 하면, 고객에게 '이때 도착합니다'라고 도착 예정 시간을 알려주기는 하지만 '이 시간이 어떻게 계산된 것인지', '어떤 데이터를 사용한 것인지', '시점에 따라 어떻게 제공되는 정보'인지는 알 수 없고, 배달원에게 '이 배달을 수행해 주세요'라고 오퍼를 보내긴 하지만 '어떤 과정으로 이 주문이 선정됐는지', '왜 해당 배달원인지'는 알 수 없습니다.

하지만 시스템을 기획하고, QA를 진행하고, 사업을 운영하고, 다른 컴포넌트와 연계하는 과정에서는 이와 같은 사항들도 고려해야 하는데요. 말씀드렸듯 눈에 잘 보이지 않았기 때문에 아래와 같은 질문을 받는 상황이 반복되고 있었습니다.

Q. 최종 정책이 뭐야?

다수의 프로젝트가 동시에 진행되며 한 시스템에 반영되다 보니, 최종 정책을 쉽게 파악하기가 어려웠습니다. 워낙 많은 프로젝트의 영향을 받아 지속적으로 Engine 정책이 업데이트되는 상황이었기에 유관 부서에서는 '그래서 어떤 정책이 최종 버전인지' 알기 어려웠습니다. 배달 영역 안에서 프로젝트 단위로 문서가 작성되고는 있었지만, 최종적으로 시스템에 반영된 버전을 찾기 위해서는 많은 문서와 히스토리를 일일이 찾아봐야만 했습니다. 가장 최신의 정책을 담고 있는 문서가 필요한 상황이었던 것이죠.

Q. Engine은 어떻게 작동하고 있어? (x100000)

Engine은 눈에 보이지 않는 '코드'로만 구성돼 있었습니다. 어떤 화면이나 스펙 문서가 없었기 때문에 기획자인 저도, 다른 컴포넌트 개발자분들도 어떤 흐름으로 Engine이 작동하고 있는지 정확하게 알 수 없었던 상태였습니다. 이런 상황에서 Engine의 동작을 고려해야 하거나 그에 영향을 받는 컴포넌트나 프로젝트가 너무나도 많았는데요. 이에 따라 Engine을 동작을 파악하기 위해 매번 Engine 개발자분들께 문의해서 기나긴 설명을 들으며 확인할 수밖에 없는 상황이 이어지고 있었습니다. 따라서 링크 하나를 전달하는 것으로 설명을 대신할 수 있는 문서가 있다면 커뮤니케이션 비용을 대폭 줄일 수 있을 것 같았습니다.

Q. 뭐라고 부를까?

거기다 한국과 일본의 팀원이 함께 만드는 서비스이다 보니 특정 기능이나 정책을 각기 다른 용어로 부르거나, 아예 명칭 자체가 없는 스펙도 많이 있었습니다. "어떤 역할을 하는 그 기능"과 같이 긴 설명을 붙여야 하거나, 서로 다른 용어를 사용하면서 혼란이 빚어지기도 했는데요. 따라서 화면에 보이지 않는 다양한 정책과 로직을 부를 수 있는 이름이 필요했습니다.

정리하면, '커뮤니케이션 비용이 계속 높아지고, 담당자 부재 시 다른 개발자가 코드를 보지 않고는 현재 상태를 알 수 없는 상황'을 해결하기 위해 정책서가 필요했던 것입니다.

잘!못! 쏘아올린 공

시작은 가볍게 했습니다. 배달 관련 정책이 여러 페이지에 흩어져 있고, 같은 내용이 여러 문서에 기재돼 있는 경우도 있다 보니 최종 정책이 무엇인지 알 수 없는 상황이 발생하는 것 같아서 이걸 한 번 합쳐보기만 해도 좋겠다는 생각에 호기롭게 Slack에 정책 문서 정리를 하겠다는 글을 올렸습니다.

최초에는 '지금 있는 문서들'을 합쳐서 하나로 만드는 것이 저의 목표였는데요. 어디서부터 잘못된 것인지, '없는 문서'를 만들어야 하는 상황으로 흘러가 버렸습니다(이제 와서 말이지만, 당시 저는 Engine 정책을 정리할 생각이 없었습니다)! 하지만 당황하지 않고! 자연스럽게! 원래 이것을 하려고 했던 것처럼! 매주 오프라인 미팅을 통해 Engine 로직을 파악하기 시작했습니다. 왜 오프라인이었냐면, 칠판이 없으면 그 어떤 것도 이해할 수 없었기 때문입니다. 😞

고민과 실행의 과정

사실 정책서라고 하면 스펙의 상위 관점에서의 정책을 정의해 놓은 문서라는 개념으로 많이 사용합니다. 따라서 어떻게 보면 'Engine 스펙 문서'라고 부르는 것이 더 맞을 수도 있겠지만, Engine 로직이 배달원 앱과 배달 과정을 모니터링하기 위한 관리자 모듈(컨트롤러)과 배달과 연계되는 시스템의 작동을 결정하므로 정책서라고 이름 붙였습니다. 정책서를 작성할 도구로는 사내에서 문서 관리 도구로 사용하고 있는 위키(Confluence)를 선택했습니다.

정책서를 작성하면서 중요하다고 생각했던 포인트는 다음과 같습니다.

필요한 것은 빠짐없이 담기
찾기 쉽게 작성하기
읽기 쉽게 작성하기
로직의 흐름을 담되, 문서 하나에 모든 것을 담지 않기
Engine 정책서에서는 Engine 동작만 다루기
정보가 중복되지 않도록 관리하기

각 포인트를 하나씩 짚어보며 어떤 과정을 거쳐 정리했는지 살펴보겠습니다.

필요한 것은 빠짐없이 담기

시스템은 있는데 정책서는 없는 시점에서 가장 어려웠던 것은 무엇이 있고, 무엇이 필요한지 모른다는 것이었습니다. 'Engine 정책서는 Engine 동작에 대한 모든 질문에 답을 줄 수 있는 문서여야 한다!'를 목표로, 먼저 그동안 받았던 Engine 동작 관련 질문들을 모았습니다. 또한 업무를 진행하는 과정에서 이미 파악하고 있던 Engine 정책과, Engine의 기능이나 정책을 변경했던 프로젝트 문서, 그외 정리가 필요하다고 생각했던 것들을 모두 한 곳에 모았습니다. 이때 체계적으로 잘 정리한다기보다는 아래와 같이 생각나는 것들을 빠르게 적어서 다른 동료들과 공유하며 빠진 것들을 체크하는 방식으로 진행했습니다.

찾기 쉽게 작성하기

정리가 필요한 것들을 한 곳에 모은 후에는 페이지 구성을 어떻게 할지 고민했습니다. 기능당 한 페이지로 구성하려니 기능별로 분량이 너무 달라서 적절한 분량으로 페이지를 나눠 묶을 필요가 있었습니다. 어떤 로직이 궁금할 때 어떤 페이지를 봐야할지 한눈에 알 수 있도록 페이지를 구분하고 싶었는데요. 우선 아래와 같이 크게 네 가지 카테고리로 정리했습니다.

Data: 주문 정보의 연계, 서비스 및 다른 로직과 연관되는 DB 필드별 업데이트 시점, 계산 로직, 외부로 제공되는 정보 및 보관 기한
Delivery Logic: 배차와 배달 로직, 배달 로직에 반영되는 관련 정책
Driver: 배달원 단위 정보, 배달원 관리 정책
External System: 외부 솔루션 사용 영역

이 카테고리를 기준으로 각 페이지별로 들어가야 할 내용을 아래와 같이 정리하면서 페이지를 구성했습니다.

읽기 쉽게 작성하기

이 문서는 누구나 읽을 수 있는 문서로 만들고 싶었습니다. '코드가 이렇습니다'하고 코드를 보여주며 코드로 이해되는 문서가 아니라 글 자체로 이해되는 문서이길 바랐습니다. 이에 개발이나 도메인 관련 지식이 깊지 않아도 쉽게 문서를 읽을 수 있도록 문서를 이해하는 데 꼭 필요한 기본적인 개념 설명을 추가했습니다. 또한 독자가 한눈에 문서의 구조나 변경된 로직의 차이점을 파악할 수 있도록 표와 페이지 레이아웃, 위계를 여러 차례 바꿔가면서 고민했습니다. 물론 담기는 내용의 특성상 술술 읽히며 바로 이해되는 정도에 이를 수는 없겠지만, 조금 시간을 들여 읽으면 누구나 충분히 이해할 수 있도록 내용을 구성해 담았습니다.

예를 들어 아래 왼쪽 그림은 ETA를 계산할 때 사용하는 개념을 설명한 것인데요. 독자가 계산 방식을 이해하려면 간단한 개념 설명을 붙여 놓는 것이 좋을 것 같아 추가해 놓은 것입니다. 오른쪽 그림은 시점별로 달라지는 계산식의 차이를 비교할 수 있게 같은 값은 같은 행에, 추가되는 값은 별도 행으로 구분해 놓았습니다.

로직의 흐름을 담되, 문서 하나에 모든 것을 담지 않기

본격적으로 문서화 작업을 시작하면서 중요하게 생각한 점은, 로직이 흘러가는 순서대로 정확하게 내용을 작성하는 것이었습니다. 어떤 로직이 어디에 위치하느냐에 따라서 결과가 완전히 달라져 버리기 때문이죠. 코드의 흐름 그대로 문서화하려고 노력했습니다.

그런데 열심히 정책서를 작성하다가 중간에 작업을 멈추고 다 갈아엎는 시점이 있었습니다. 주문에 맞는 후보 배달원를 선정하는 배차 로직을 문서 하나에 담으려다 보니 문서가 너무 방대해졌기 때문이었습니다. '로직의 흐름을 다 담고 싶다'와 '빠지는 내용이 없었으면 좋겠다' 이 두 가지 조건을 다 충족하려다 보니 적는 내용이 많아졌던 것이죠! 그래서 지금까지 작성해 온 것이 조금 아깝긴 했지만, 문서 작성 콘셉트를 완전히 바꾸기로 했습니다.

흐름을 담는 문서를 하나 만든다.
상세한 정책을 담는 문서를 별도로 만들어서 링크를 건다.

또한 상세 정책에도 표시할 수 있도록 각 흐름별로 코드를 붙여 놓았는데요. 정책서 발행 후 이 코드가 제 예상보다 훨씬 더 실제 커뮤니케이션에 도움이 된다는 피드백을 받을 수 있었습니다.

Engine 정책서에서는 Engine 동작만 다루기

이 문서는 무엇보다 Engine의 동작을 정리하기 위한 문서이기 때문에 다른 컴포넌트에 대한 내용은 최대한 배제하기 위해 노력했습니다. 아무래도 다른 컴포넌트의 변경 사항을 모드 제때 알고 다 담을 수 없기 때문에 오히려 보는 사람을 혼란스럽게 할 뿐입니다. 따라서 아래와 같은 기준을 두고 다른 컴포넌트에 관한 내용은 최대한 다른 문서로 분리하거나 링크로 대체했습니다.

컴포넌트간 연계되는 동작만 기술한다.
- 다른 컴포넌트에서 받아오는 정보나 특정 응답에 따른 Engine 처리만 기술한다.
- 다른 컴포넌트의 스펙을 알 수 있도록 스펙 문서를 링크한다.
다른 컴포넌트의 정책에 따라 Engine의 동작이나 대응이 달라지는 경우 별도 문서를 구성하고 해당 스펙 버전에 대한 날짜를 표시해 둔다.

정보가 중복되지 않도록 관리하기

마지막으로 정책서에 최신 정책을 업데이트할 예정이었기에, 정책 변경 시 다른 문서에 반영할 필요가 없도록 배달원 앱과 관리자 모듈의 스펙 문서를 확인해 정책 관련 내용을 정책서 링크로 대체했습니다. 또한 파편화돼있던 정책 문서들을 하나의 위키로 옮겼습니다. 정책을 기재하는 문서는 정책서로 일원화해서 업데이트할 때 해야 하는 작업을 줄이고, 각기 다른 문서에 서로 다른 스펙이 기재됨으로 발생하는 혼란을 줄이고자 했습니다.

Engine 정책서 탄생 후 효과는?

이 글을 쓰고 있는 시점은 정책서를 완성한 지 6개월 정도 흐른 시점인데요. 현재 한국과 일본 동료분들은 정책서를 통해 서로 소통하며 시스템을 이해하고 있습니다(👍). QA와 Delivery 기획은 물론 다른 컴포넌트 개발자분들도 함께 보는 문서가 된 것인데요. 이와 같이 정책서를 통해 시스템을 이해하고 소통하게 되면서 어떤 변화가 있었을까요?

먼저 정책서 탄생 후 Engine 개발 프로세스 다음과 같이 개선됐습니다.

We are on the same page! 인식을 맞췄어요!

정책서를 기반으로 소통하며 로직을 이해하는 과정을 거치면서 각자 이해하고 있는 것이 맞는지 확인할 수 있게 되었습니다. 현재 스펙을 파악할 때도 정책서를 보다가 이해가 되지 않는 부분만 추가로 질문하게 되었고, 알고 있던 스펙과 정책서에 기재돼 있는 것이 다른 경우 개발쪽에 확인을 통해 점차 더 보안해 나갈 수 있었습니다. 이런 방식으로 업무를 진행하다 보니 함께 일하는 모두가 시스템을 동일하게 이해하고 있다는 믿음을 쌓을 수 있었습니다.

QA에서 사용할 수 있는 기준이 생겼어요!

사실 스펙 문서를 작성하면 가장 자세하게 봐주시는 분들은 QA 파트분들입니다. 기존에는 QA 파트분들이 확인할 수 있는 게 프로젝트 문서뿐이다 보니, 다른 파트의 영향 범위를 파악할 때 기존의 경험에 의존하는 방법 밖에 없었는데요. 이제 정책서를 볼 수 있게 되면서 생각하지 못했던 부분까지 검증해 주시고 있습니다(글을 쓰는 지금도 하나 발견됐어요!). 덕분에 정책서도 계속 보완하고 있습니다. 이 자리를 빌려 감사드립니다!

어디를 어떻게 개선할지, 영향 범위는 어떻게 될지 확실하게 알 수 있어요!

시스템을 개선하거나 기능을 추가할 때, 기존에는 내가 알고 있는 시스템 구성을 바탕으로 영향 범위를 파악할 수밖에 없었습니다. 그 과정에서 누락된 경우 동료들의 지적을 통해서 다시 파악해야 했는데요. 이제 정책서를 한번 훑어보면서 영향 범위를 파악할 수 있게 되었습니다. 그 덕분에 전보다 더 상세하게 영향 범위를 파악할 수 있게 되었고, 사전에 사업측 혹은 유관 부서와 더욱 꼼꼼하게 대응 방안을 검토할 수 있게 되었습니다.

이름이 생겼어요!

이름을 붙일 수 있는 특정 기능들에는 이름을 붙였고, 각 로직 흐름에 코드도 붙여뒀기 때문에 이 두 가지를 바탕으로 더욱 쉽게 소통할 수 있게 되었습니다. 질문할 때나 소통할 때 한국과 일본 팀원이 모두 같은 명칭으로 이야기할 수 있게 되었고, 애매한 상황이 발생하면 정책서 링크를 공유하며 지금 무엇에 관한 이야기를 하고 있는지 바로 알려줄 수 있게 되었습니다. 정책서는 지속적으로 업데이트하고 있기 때문에, 새로운 기능을 만들거나 추가할 때 어떤 이름을 붙일지 함께 고민하며 작명하는 시간이 있기도 합니다(🙂).

Engine 기획자가 생겼어요!

Engine 정책서를 완성하기 전까지는 Engine 스펙을 전반적으로 이해하고 있는 기획자가 없는 상태였는데요. 매주 오프라인 미팅을 진행하고 정책서를 작성하는 과정에서 Engine 스펙을 더 정확하게 이해할 수 있었고, 이를 바탕으로 Engine 기획을 전반적으로 검토할 수 있는 기획자가 될 수 있었습니다. 이제 여러 프로젝트에서 Engine과 관련된 범위를 검토할 때 개발자가 아닌 기획자가 검토하고 답을 줄 수 있는 상태가 되었습니다.

마치며

로직을 꼭 문서화할 필요가 있을까 싶기도 했지만 이렇게 정리하고 보니 많은 곳에서 활용되고 있었습니다. 화면으로 표현할 수 없는 로직을 기획자와 QA, 관련 사업 부서들까지 이해할 수 있는 글로 정리하는 것에는 확실한 장점이 있는 것 같습니다. 특히 저희와 같이 언어와 문화가 서로 다른 사람이 함께 모여 긴밀하게 협업해야 하는 환경에서는 말이죠. 물론 아직까지 정책서에 반영하지 못한 부분도 있을 것이고 누락된 로직도 있겠지만, 많은 분들이 관심을 갖고 보완해 주고 계시기 때문에 점점 시스템과 닮아가는 정책서가 될 것이라고 믿습니다!

개인적으로는, 이와 같이 정책서를 작성하는 과정에서 담당하는 시스템을 완전히 이해할 수 있다는 점이 정말 좋았습니다. 사실 저는 관리자 화면 기획으로 입사했기 때문에 원래 Engine은 제 업무 범위 밖이었는데요. Engine 스펙 전반을 이해하게 되면서 Engine 기획까지 업무 범위를 확장할 수 있었습니다. 또한 시스템 전반을 이해하고 이를 바탕으로 일하게 되니 역량 향상에도 큰 도움이 되었다고 생각합니다.

만약 기획자로서 담당하는 서비스나 상품의 로직에 대한 문서를 만들까 고민하고 계시다면, "일단 해보겠습니다!"라고 선언해 보면 어떨까요? 일단 공을 쏘아 올리면, 미래의 나와 멋진 동료분들이 함께 해결해 줄 테니까요!

보이지 않는 로직, 읽을 수 있는 문서로 만들기!

댓글