명세 문서

무엇을 왜 만들지는 PRD에 적힙니다. 쿠폰 기능이라면 왜 지금 이것을 하는지, 이번에 어디까지 하는지, 무엇이 되면 끝인지가 그 문서에 들어갑니다. 여기까지는 읽는 사람 모두에게 같은 값을 합니다.

그런데 그 문서를 들고 자리에 앉아 실제로 만들려고 하면 다른 종류의 질문이 쏟아집니다. 쿠폰 코드를 입력하는 칸이 비어 있을 때 확인 버튼이 눌리는지, 틀린 코드를 넣으면 입력칸 아래에 무슨 문구가 뜨는지, 그 문구는 몇 초 뒤에 사라지는지, 이미 쓴 코드와 만료된 코드가 같은 문구를 쓰는지. 하나하나는 사소하지만 답하지 않으면 코드를 한 줄도 못 씁니다.

페이지덱에서 문서 공유 초대 기능을 만들 때 실제로 그런 날이 있었습니다. 태오가 오전에 세 번, 오후에 네 번 지현에게 물으러 왔습니다. 이미 초대한 사람을 또 초대하면 어떻게 되는지, 초대를 보낸 뒤 취소할 수 있는지, 취소하면 상대가 받은 메일의 링크는 어떻게 되는지가 차례로 나왔습니다. 지현은 그 자리에서 답했고 답은 대부분 합리적이었지만, 그 일곱 개의 결정은 아무 데도 적히지 않았습니다. 민서는 취소 상태의 화면을 모르는 채 시안을 그리고 있었고, 두 주 뒤 검수에서 서로 다른 것을 만들었다는 사실이 드러났습니다.

되묻는 일 자체가 문제는 아닙니다. 문제는 되묻지 않은 항목입니다. 열 개 중 일곱 개를 묻고 세 개는 각자 알아서 정하면, 그 셋이 어긋났다는 사실은 코드와 시안을 붙여 보는 날에야 드러납니다. 그때 고치는 값은 미리 정해 두었을 때의 몇 배입니다. 미리 정하면 회의 30분이지만, 만든 뒤에 어긋나면 화면을 다시 그리고 코드를 다시 짜고 검수를 다시 도는 데 며칠이 듭니다.

명세 문서는 그 질문들을 만들기 전에 한 번에 뽑아 적어 두자는 제안입니다. 적는 단위가 PRD와 다릅니다. PRD가 이번 일의 경계를 그린다면 이 문서는 그 경계 안을 화면과 조건으로 채웁니다. 목표는 완벽한 문서가 아니라 되묻는 횟수를 줄이는 것이고, 되묻지 않고도 같은 것을 만들었다면 그 문서는 제 몫을 한 것입니다.

아래 묶인 용어는 종류 한 갈래뿐이고 넷이 들어 있습니다. 넷은 서로 다른 문서가 아니라 같은 기능을 네 각도에서 적은 것입니다. 무엇을 하는지는 기능 명세가, 그것이 어느 화면 어디에 놓이는지는 화면 정의서가, 어떤 순서로 갈라지는지는 플로우 차트가, 무엇에서 무엇으로 넘어가는지는 상태 다이어그램이 맡습니다.

1. 기능 명세 — 기능 하나가 어떤 조건에서 어떻게 동작하는지를 문장으로 적습니다. "초대 메일이 발송된 지 7일이 지나면 링크가 만료되고, 만료된 링크를 누르면 재요청 안내 화면으로 보낸다" 처럼 조건과 결과가 짝을 이루게 씁니다. 네 문서 가운데 가장 넓은 자리를 차지하고, 나머지 셋은 이 문장들을 다른 방식으로 비춰 봅니다.
2. 화면 정의서 — 화면을 하나씩 세워 놓고 그 안의 요소와 각 요소의 동작을 적습니다. 초대 화면이라면 이메일 입력칸, 권한 선택, 보내기 버튼, 이미 초대된 사람 목록이 항목으로 서고, 항목마다 비었을 때·입력 중일 때·오류일 때가 붙습니다. 디자인 시안이 보여 주는 것은 대개 정상 상태 하나라서 나머지 상태는 이 문서가 채웁니다.
3. 플로우 차트 — 사용자가 밟는 순서와 갈라지는 지점을 도형으로 그립니다. 초대 링크를 누른 사람이 이미 계정이 있으면 바로 문서로, 없으면 가입 화면으로 갈라지는 식입니다. 글로 적으면 조건문이 겹쳐 읽기 어려워지는 부분을 그림이 한눈에 보여 줍니다.
4. 상태 다이어그램 — 하나의 대상이 가질 수 있는 상태와 그 사이를 오가는 길을 그립니다. 초대 한 건은 발송됨·수락됨·거절됨·만료됨·취소됨 다섯 상태를 가지고, 어느 상태에서 어느 상태로 갈 수 있는지를 화살표로 잇습니다. 화살표가 없는 칸이 곧 막아야 할 동작이라서, 만료된 초대를 수락하면 무슨 일이 생기는지 같은 질문이 그림에서 저절로 드러납니다.

넷 다 쓸 필요는 없습니다. 고르는 기준은 그 기능이 어디서 복잡해지는가입니다. 화면은 단순한데 조건이 많으면 기능 명세만으로 충분하고, 거치는 화면이 여럿이면 플로우 차트가 붙고, 하나의 대상이 여러 상태를 오가면 상태 다이어그램이 값을 합니다. 넷을 다 그리는 데 드는 시간이 만드는 시간보다 길어지면 그 문서는 이미 제 몫을 넘긴 것입니다. 초대 기능처럼 상태가 다섯인 일에는 기능 명세와 상태 다이어그램 둘이면 대개 충분합니다.

어느 종류를 쓰든 채워야 할 칸은 대체로 같습니다. 다섯 칸이고, 빠뜨리면 그 칸을 읽을 사람이 되묻게 됩니다.

1. 대상과 범위 — 이 문서가 다루는 화면과 기능이 어디까지인지 먼저 못 박습니다. 초대 기능을 적으면서 초대받은 사람의 가입 절차까지 포함하는지 아닌지를 첫 줄에 적어 둡니다.
2. 요소 목록 — 화면에 놓이는 것을 빠짐없이 셉니다. 버튼과 입력칸뿐 아니라 안내 문구, 비어 있을 때 보이는 화면, 불러오는 동안 보이는 표시까지 항목으로 세웁니다.
3. 동작과 조건 — 누르면 무엇이 일어나는지를 조건과 짝지어 적습니다. "보내기를 누르면 초대가 발송된다" 는 절반이고, 권한을 고르지 않았을 때·이미 초대된 주소일 때·한도를 넘겼을 때가 붙어야 한 칸이 찹니다.
4. 예외와 오류 — 정상 경로가 아닌 경우를 모읍니다. 네트워크가 끊겼을 때, 같은 버튼을 두 번 눌렀을 때, 권한이 없는 사람이 주소를 직접 열었을 때 무엇을 보여 줄지가 여기 들어갑니다. 실무에서 되묻는 질문의 대부분이 이 칸에서 나옵니다.
5. 인수 조건 — 이 기능이 끝났다고 인정받기 위한 조건입니다. 체크할 수 있는 문장으로 적어야 하고, 검수하는 사람은 이 목록을 그대로 따라가며 하나씩 확인합니다.

규칙이 화면을 넘어 제품 전체에 걸리면 그 부분은 제품 정책으로 따로 뺍니다. 초대 권한을 누가 가질 수 있는지는 초대 화면 하나의 문제가 아니라 모든 문서와 모든 플랜에 걸리는 규칙이라 정책 문서에 적고 여기서는 링크만 겁니다. 두 곳에 같은 규칙을 적으면 한쪽만 고쳐지는 날이 반드시 옵니다.

쓰는 사람과 읽는 사람도 정해져 있습니다. 쓰는 쪽은 대개 그 기능을 맡은 프로덕트 매니저이고, 화면 안의 상태가 많은 기능은 디자이너가 함께 채웁니다. 읽는 쪽은 셋으로 갈리고 각자 다른 칸을 봅니다. 개발자는 동작과 조건, 예외와 오류를 보고 얼마나 걸릴지를 답합니다. 디자이너는 요소 목록을 보고 그려야 할 상태가 몇 개인지 세는데, 와이어프레임을 먼저 그려 놓고 그 그림을 보며 이 문서를 같이 채우는 순서가 흔합니다. 품질 보증을 맡은 쪽은 인수 조건과 예외 칸을 그대로 검수 목록으로 옮깁니다. 그래서 한 칸이 비면 그 칸을 읽는 사람만 멈춥니다. 예외 칸이 비어 있으면 개발은 굴러가는데 검수에서 판정할 기준이 없습니다. 쓰는 일도 한 번으로 끝나지 않습니다. 만드는 동안 바뀐 결정이 문서로 돌아오지 않으면 두 주 만에 낡고, 낡은 문서는 없는 것보다 나쁩니다. 아무도 의심하지 않고 그대로 만들기 때문입니다.

기계가 읽는 명세도 있습니다. 프로그램끼리 주고받는 창구를 적을 때 쓰는 OpenAPI가 그것입니다. 사람이 읽는 문장 대신 정해진 형식으로 적어 두면 도구가 그 파일을 읽어 문서 화면과 검증 코드를 만들어 냅니다. 사람이 읽는 명세와 목적은 같고, 독자가 사람이냐 도구냐만 다릅니다.

"명세에 없는 경우라 일단 막아 뒀어요. 빈 값으로 저장되면 뒤에서 다 깨져서요."

문서에 답이 없어 개발자가 임시로 정했다는 보고이고, 확인해 달라는 요청이기도 합니다.

"이 화면 정의서 기준으로 만들면 되죠? 지난주에 바뀐 건 반영돼 있나요?"

문서가 최신인지를 묻는 말입니다. 낡은 문서로 만들면 두 주가 통째로 날아갑니다.

"상태 다이어그램부터 그려 주세요. 초대를 취소하면 어디로 돌아가는지가 지금 안 정해져 있어요."

글로 적힌 조건만으로는 빠진 경로가 보이지 않으니 그림으로 확인하자는 제안입니다.

페이지덱의 문서 공유 초대 기능은 그 뒤로 순서가 바뀌었습니다. 지현이 기능 명세와 화면 정의서 초안을 먼저 올리고, 민서가 화면별 상태를 채우면서 비어 있는 자리를 댓글로 짚습니다. 초대 목록이 0건일 때 무엇을 보여 줄지가 첫 번째 댓글이었습니다. 태오는 예외 칸을 읽고 같은 주소로 두 번 초대했을 때의 동작을 되물었는데, 이번에는 그 답이 문서에 적혔습니다.

문서를 닫는 시점도 정해 두었습니다. 지현은 수요일까지 댓글을 받고 목요일에 확정한 뒤 착수합니다. 그 뒤에 들어오는 변경은 문서를 고치고 고친 줄에 날짜를 남기는 절차를 거칩니다. 절차가 번거로워 보이지만, 이 한 단계가 있어야 구두로 바뀐 내용이 검수 때 분쟁으로 돌아오지 않습니다.

가장 흔한 오해는 디자인 시안이 있으면 이 문서가 필요 없다고 보는 것입니다. 시안이 훨씬 구체적으로 보이고 화면을 그대로 보여 주니 자연스러운 생각입니다. 하지만 시안이 담는 것은 눈에 보이는 상태이고, 그것도 대개 모든 것이 잘 풀린 한 장면입니다. 초대 목록이 비었을 때, 주소를 잘못 입력했을 때, 한도를 넘겼을 때의 화면은 시안 파일에 없는 경우가 많고, 있더라도 언제 그 화면으로 넘어가는지는 그림이 말해 주지 않습니다. 시안만 들고 만들면 개발자가 그 조건을 각자 정하게 되고, 검수 때 서로 다른 것을 만들었다는 사실이 드러납니다. 둘은 경쟁하는 문서가 아니라 서로의 빈칸을 채웁니다. 시안이 어떻게 보이는지를 맡고 이 문서가 언제 그렇게 보이는지를 맡습니다.

두 번째는 자세할수록 좋은 문서라고 보는 것입니다. 되묻는 일을 줄이려고 쓰는 문서이니 더 적을수록 안전해 보입니다. 그런데 30쪽짜리 문서는 아무도 끝까지 읽지 않습니다. 버튼의 여백이 몇 픽셀인지까지 적으면 정작 중요한 예외 조건이 그 사이에 묻히고, 디자인이 조금만 바뀌어도 문서가 낡아 다음부터는 문서를 안 믿게 됩니다. 실제로 갈라야 할 선은 나중에 누군가 다시 물어볼 항목인지입니다. 여백은 디자인 파일이 답하고 만료된 초대를 수락하면 어떻게 되는지는 이 문서가 답합니다.