릴리스 노트

배포가 조용히 지나가던 시절이 있었습니다. 만든 것을 사용자에게 내보내는 일을 릴리스라고 하는데, 그 뒤에 아무 안내가 붙지 않으면 사용자는 어제까지 있던 버튼이 사라진 것을 스스로 발견하게 됩니다.

그러면 같은 일이 세 곳에서 동시에 벌어졌습니다. 사용자는 고장이 났다고 생각해 문의를 넣고, 고객 지원은 그게 바뀐 것인지 고장인지 몰라 개발팀에 물어보고, 개발팀은 어제 나간 것이 무엇이었는지 커밋 기록을 뒤집니다. 화면 한 곳을 옮긴 배포 뒤에 문의가 서른 건 들어오는 날이 분기마다 있었습니다. 고친 것이 없는데 일이 늘어나는 날입니다.

릴리스 노트는 그 안내를 고정된 산출물로 만든 것입니다. 바뀐 것을 기능 이름이 아니라 사용자가 할 수 있게 된 일로 적어서, 사용자가 묻기 전에 먼저 알려 줍니다. 한 번 쓰는 데 20분이 드는 글이 문의 서른 건을 막는 계산이 서기 때문에 내부 규칙으로 자리 잡았습니다.

한 편의 릴리스 노트에는 다섯 가지가 들어갑니다.

1. 날짜와 버전입니다. 언제 나간 변경인지가 붙어 있어야 사용자가 자기가 겪은 일과 맞춰 볼 수 있습니다. 개발자가 쓰는 제품이면 버전 번호를, 일반 사용자용 제품이면 날짜만 적는 경우가 많습니다.
2. 변경을 성격별로 묶은 구획입니다. 새로 생긴 기능, 기존 기능의 개선, 고친 오류, 곧 없어질 예정인 것을 나눠 씁니다. 마지막 묶음은 미리 알리고 사용을 말리는 상태를 뜻하는 디프리케이션 안내가 들어가는 자리입니다.
3. 항목마다 한 줄 설명입니다. 여기가 이 글의 품질을 정합니다. "검색 엔진을 v2로 교체했습니다" 는 만든 쪽의 말이고, "문서 제목뿐 아니라 본문 안의 문장까지 검색됩니다" 는 쓰는 쪽의 말입니다. 뒤쪽으로 적으면 사용자가 자기에게 해당하는지 바로 판단합니다. 기준은 하나입니다. 읽고 나서 할 수 있는 일이 달라지는지를 적습니다.
4. 영향을 받는 사람과 해야 할 일입니다. 관리자가 설정을 한 번 켜 줘야 하는 변경, 연동해 둔 쪽에서 코드를 고쳐야 하는 변경은 따로 표시합니다. 기존 사용자의 코드를 깨뜨리는 변경을 브레이킹 체인지라고 부르는데, 이것이 한 줄 아래에 묻혀 있으면 안내를 한 것으로 치지 않습니다.
5. 더 볼 곳입니다. 자세한 설명이 있는 도움말 주소와 문의 경로를 끝에 둡니다. 안내를 짧게 쓰는 대신 더 알고 싶은 사람이 갈 곳을 열어 두는 자리입니다.

길이는 변경의 크기에 맞춥니다. 오류 수정 두 건이면 세 줄이고, 요금제가 바뀌는 변경이면 화면 사진과 예시가 붙어 한 화면을 채웁니다. 알릴 규모를 등급으로 나눠 둔 런치 티어가 있으면 그 등급이 이 길이를 대체로 정해 줍니다.

쓰는 사람은 대개 프로덕트 매니저이고, 출시 규모가 크면 프로덕트 마케팅 매니저가 문구를 맡습니다. 어느 쪽이 쓰든 사실 확인은 개발자가 합니다. 무엇이 실제로 나갔고 무엇이 이번 배포에서 빠졌는지는 만든 사람만 알기 때문입니다. 고객 지원도 발행 전에 한 번 읽습니다. 이 문장으로 문의가 늘어날지 줄어들지를 가장 잘 아는 쪽입니다.

읽는 사람은 셋으로 갈립니다. 첫째는 매일 쓰는 사용자입니다. 자기가 쓰는 화면이 바뀌었는지만 확인하고 나가므로, 해당 없는 항목이 위에 길게 깔리면 끝까지 읽지 않습니다. 둘째는 팀의 관리자입니다. 권한과 요금과 보안에 걸리는 변경을 찾고, 자기 팀에 따로 공지할지 판단합니다. 셋째는 사내의 세일즈와 고객 지원입니다. 고객이 물을 것에 답하려고 읽기 때문에, 이 셋 중 가장 꼼꼼히 읽는 독자가 여기입니다. 사내 독자가 먼저 읽고 되물은 지점은 고객도 같은 자리에서 걸립니다.

한 편으로 셋을 다 만족시키려면 순서가 중요합니다. 영향이 큰 변경을 위에 두고 내부 개선을 아래에 두면, 세 독자 모두 자기가 필요한 지점에서 멈출 수 있습니다.

"이 항목은 릴리스 노트에 넣지 말죠. 내부 구조만 바꾼 거라 사용자가 볼 게 없어요."

독자에게 달라지는 것이 없으면 적지 않는다는 기준을 적용한 판단입니다.

"이번 건은 릴리스 노트만 올리고 전체 메일은 안 보냅니다."

알릴 필요는 있지만 밀어서 알릴 만큼은 아니라는 판단입니다.

"고객이 릴리스 노트 보고 문의했어요. 이 문장이 오해를 만들었습니다."

안내가 문의를 줄이는 대신 늘렸으니 표현을 고쳐야 한다는 보고입니다.

페이지덱이 문서 공유 링크에 만료 기간을 붙였을 때, 첫 초안에는 "공유 링크 만료 정책을 적용했습니다" 라고 적혀 있었습니다. 지현이 그 문장을 "공유 링크에 7일·30일·무기한 중 하나를 고를 수 있고, 기본값은 30일입니다" 로 바꿨습니다. 기본값이 바뀌면 기존 링크가 언제 막히는지를 관리자가 먼저 알아야 했기 때문입니다.

태오가 이미 만들어진 링크는 그대로 유지된다는 사실을 확인해 줬고, 그 한 줄이 함께 들어갔습니다. 수아는 그 항목을 그대로 복사해 담당 고객들에게 먼저 보냈습니다.

개발 기록을 옮겨 적는 글로 아는 경우가 가장 많습니다. 바뀐 내용을 적는다는 점이 같으니 커밋 목록을 다듬으면 될 것처럼 보입니다. 하지만 두 글의 독자가 다릅니다. 개발 기록은 코드를 아는 사람이 무엇을 건드렸는지 찾으려고 읽고, 릴리스 노트는 코드를 모르는 사람이 자기 업무가 달라지는지 확인하려고 읽습니다. 앞쪽 말로 쓰인 릴리스 노트는 읽는 쪽에서 아무 결정을 만들지 못하고, 결국 문의로 되돌아옵니다.

빠짐없이 적을수록 좋다고 보는 것도 흔합니다. 성실해 보이는 판단이지만 읽는 시간은 정해져 있습니다. 내부 개선 열두 줄 아래에 요금이 바뀐다는 항목이 놓이면 그 항목은 전달되지 않은 것과 같습니다. 무엇을 넣을지가 아니라 무엇을 위에 둘지가 이 글의 실제 작업입니다.