쉽게 읽히는 티켓 쓰는 법
일단 티켓(ticket)이 무엇인지부터 알아보자. 티켓은 개발자에게 보내는 의뢰서다. "이런저런 기능을 만들어주세요~"라며 내용을 써서 보내면, 개발자는 그 내용을 토대로 개발을 시작한다.
티켓은 내가 원하는 결과물과 그 결과물을 실현시켜주는 이를 이어주는 매개체다. 티켓 내용이 얼마나 잘 작성되었는지에 따라 개발 과정과 결과물의 퀄리티가 달라진다. 사람은 같은 단어를 놓고도 전혀 다른 것을 떠올리는 동물이기 때문에, 모두가 같은 생각을 하게 만드는 것이 중요하다. 이를 위해서는 티켓을 깔끔하게 작성해야 한다.
1. 기본 원칙
티켓은 제작 주문서와 비슷하다. 간결함과 명확함이 핵심이다. 중복되는 내용은 합치고 설명이 쓸데없이 길어지지 않도록 주의하자. 길어 보이면 일단 읽기 귀찮아진다.
> 고치기 전: 서버의 연결 상태가 항상 ONLINE으로 유지되도록 업데이트가 필요
> 고친 후: 서버가 항상 'ONLINE' 상태로 유지되도록 업데이트
만약 요청 항목이 여러 개라 어쩔 수 없이 분량이 길어질 경우 티켓을 여러 개로 쪼개자. 종류가 다양하면 이해하기 힘들 뿐만 아니라 작성한 코드를 점검하는 과정도 복잡해진다. 되도록이면 '1티켓=1변경'을 원칙 삼아 심플함을 유지하자.
2. 제목 짓기
티켓 제목은 애매하면 안 된다. 제목만 읽어도 코드의 어떤 부분을 어떻게 변경해야 할지 대충 감이 올 정도로 구체적이어야 한다(동시에 간결해야 한다. 참 어렵다). 사람 간의 커뮤니케이션에는 맥락이 중요하다. 맥락이 빨리 파악될수록 읽는 사람의 마음이 편해진다. 요리사 백종원 씨가 "식당 간판은 무조건 직관적이어야 한다"라고 말하는 것과 일맥상통한다.
> 고치기 전: 회원가입 페이지 업데이트 ('뭘 업데이트하는 거지? 테마 색깔? 버튼 위치? 입력 필드? 페이지 비율? 아니면 싹 다 갈아엎는 건가?')
> 고친 후: 회원가입 페이지 버튼 위치 변경 ('버튼 위치를 바꾸는 작업이겠군')
제목이 풍기는 뉘앙스와 실제 내용이 최대한 일치하도록 신경 써야 한다. 자신이 예상한 대로 흘러가고 있다는 안심감을 주어야 한다. 제목을 잘 지어야 개발하는 사람도 알아듣기 쉽고, 나중에 검색할 때도 잘 걸린다.
3. 본문 내용
이제 티켓에 들어가야 하는 기본 내용을 알아보자. 사실 어떤 형식이 딱 정해져 있는 것은 아니다. 같이 일하는 개발자가 쉽게 이해하고 실행에 옮길 수 있으면 어떤 형식이든 상관없다. 자유형식이지만, 어디서부터 시작해야 할지 모르겠다면 아래 형식을 베끼는 것부터 시작해보자. 그다음에 사내 프로세스에 맞게 변형시켜가면 된다.
배경 (Motivation)
사람의 뇌는 왜라는 질문에 민감하게 반응한다. 지나가는 사람이 현금 100만 원을 쥐어준다면 "아싸!"보다는 "나한테 왜?"라는 반응이 먼저 나올 것이다. 개발도 똑같다. "이런 기능을 왜 굳이 넣으려는 거지?"와 같은 의문이 빨리 해소되어야 속도가 붙는다. 배경 상황을 알면 요구 사항에 적힌 것보다 더 나은 방법을 생각해낼 수도 있고, 연결된 다른 코드를 변경해야 할 때 어떤 식으로 바꿀지 의사결정을 더 빠르게 내릴 수 있다.
> 예: 서비스를 처음 써보는 사람들의 이탈률을 줄이기 위해
현재 상태 (Status Quo)
왜 개발해야 하는 지를 설명했으면 이제 현재 상태를 묘사할 차례다. 작성자의 의견은 자제하고 최대한 팩트만 전달하자.
> 예:
1. '서비스 사용해보기' 버튼을 누르면 회원가입 페이지로 이동합니다.
2. 회원가입 페이지에서 실제 가입까지 이루어지는 비율은 10% 미만입니다.
요구 사항 (Requirement)
무엇이 바뀌어야 하는지 요구하는 항목이다. 요구 사항은 무조건 구체적이어야 한다. "더 깔끔하게 바꿔주세요" 같은 요구 사항은 실행에 옮길 수 없다. 개발자가 How에 집중할 수 있도록, What을 디테일하게 작성하자.
> 예:
1. '서비스 사용해보기' 버튼을 누르면 회원가입 페이지 대신 데모 페이지로 이동하도록 변경 (회원가입 없이 체험해볼 수 있도록).
2. 데모 페이지 오른쪽 상단에 '가입하기' 버튼 배치. (예시 스크린샷을 첨부하면 더욱 좋다)
3. '가입하기' 버튼의 추적 픽셀 삽입 (체험 후 가입으로 넘어가는 비율 추적용)
인수 시나리오 (Acceptance Scenario)
요구 사항대로 개발이 되었을 때 결과물이 어떤 모습인지 묘사해주면 된다. 개발이 잘 되었는지 테스트할 때 유용하게 활용할 수 있다.
> 예:
1. 홈페이지에서 '서비스 사용해보기' 버튼을 누릅니다.
데모 페이지로 이동합니다.
데모 페이지에서 서비스를 자유롭게 체험해볼 수 있습니다.
데모 페이지 오른쪽 상단에 '가입하기' 버튼이 보입니다.
'가입하기' 버튼을 누르면 회원가입 페이지로 이동합니다.
2. KPI 대시보드에서 사용자들이 체험 후 가입으로 넘어가는 비율을 확인할 수 있습니다.
4. 본문 포장하기
글을 깔끔하게 포장하면 가독성을 크게 높일 수 있다. 내용이 아무리 좋아도 한눈에 알아보기 힘들면 그만큼 전달력이 떨어진다.
표
예시 데이터를 붙일 경우 글보다는 표로 보여주는 것이 좋다. 'Don’t tell but show(말로 하지 말고 보여줘)'라는 영어 문장처럼, 사람은 그림에 더 적극적으로 반응한다. 긴 설명은 표로 묶어서 보여주자. 그래야 관계성이 한눈에 들어온다.
글머리 기호
굳이 표로 만들 내용은 아니지만 뭔가의 목록을 보여줄 때는 글머리 기호를 붙이자. 용도에 따라 점을 찍거나, 번호, 알파벳, 가나다 형식으로 매기면 된다.
- 점은 목록의 항목이 수평적일 때
- 번호는 순서를 알려줄 때
- 알파벳/가나다는 선택지를 보여줄 때
텍스트 포맷
요즘엔 마크다운(markdown) 문법을 기본으로 적용하는 편집기가 많다. 적절히 활용하면 가독성을 더욱 높일 수 있다.
- 제목, 소제목, 본문이 구분되도록 글자 크기를 조정하자.
- 기술 관련 키워드는 백틱( ` )으로 감싸자(예: 서버 요청을 `HTTPS` 방식으로 변경).
- 색깔은 특별한 경우를 제외하고는 흑백으로 유지하자(색깔이 많으면 혼란스럽다).
- 관련 링크는 본문 중간중간에 넣는 것보다 한 곳에 모아져 있는 편이 읽기 편하다.
읽기 쉬운 티켓은 커뮤니케이션 비용을 줄여준다. 개발 도중에 일어날 수많은 오해와 기능 누락과 쓸데없는 회의를 예방할 수 있다. 티켓에 개발 디테일뿐만 아니라 나의 의도가 잘 담겨있는지를 살펴보면서 작성하면 도움이 될 것이다.
정리
- 티켓 내용은 간결함과 명확함이 핵심이다.
- '1티켓=1변경'으로 심플함을 유지하자.
- 티켓 제목은 간결하고 구체적으로.
- 티켓에는 배경, 현재 상태, 요구 사항, 인수 시나리오가 들어가야 한다.
- 표, 글머리 기호, 텍스트 포맷으로 가독성을 높이자.
*본 내용은 요즘IT와 함께 작성한 글입니다.
