[TW] Release Note 톺아보기

시작하며

안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리)과 Sandy(차신영)입니다.

지금까지 테크니컬라이팅 팀에서는 테크니컬라이팅 관련 포스팅을 기고하고 있는데요. 이번 포스팅을 시작으로 다양한 기술문서에 대해 상세히 알아보는 톺아보기 시리즈를 새롭게 선보이게 되었습니다.

제목에 있는 “톺아보기”라는 단어를 보시고, 생소하기도 하고 오타는 아닐까 하는 의심이 드신 분들도 계셨을 텐데요. 우리말샘 사전에 따르면 “톺아보기”는 ‘샅샅이 톺아 나가면서 살피다’라고 명시가 되어있습니다. ‘틈이 있는 곳마다 모조리 더듬어 뒤지면서 찾다’라는 뜻의 ‘톺다’와 ‘보다’가 합쳐진 순우리말인데요.

기존 테크니컬라이팅 시리즈에서 테크니컬 라이터로서 글쓰기 팁과 노하우를 소개해드렸다면, 톺아보기 시리즈는 테크니컬라이터가 작성하는 다양한 기술문서의 종류와 구성, 그리고 이런 문서들의 목적 등을 상세히 파헤쳐 보려고 합니다. 실제로 기술문서를 작성하는 분들이나, 기술문서를 자주 접하는 분들께 도움이 되길 바랍니다.

첫 톺아보기 시리즈로 소프트웨어의 개선 사항과 추가 기능들을 요약한 문서인 릴리즈 노트(Release Note)를 준비했는데요. 사실 외래어 표기법에 따르면 ‘릴리스 노트’가 맞는 표기이지만, 많은 분들이 ‘릴리즈 노트’ 표기법에 더 익숙하신 것 같아 이 포스팅에서는 ‘릴리스 노트’ 대신 ‘릴리즈 노트'로 표기하였습니다.

그럼, 지금부터 릴리즈 노트 톺아보기를 시작해 보도록 하겠습니다.

릴리즈 노트란?

본론을 시작하기 전에 릴리즈 노트의 정의를 한번 짚어보겠습니다. 릴리즈 노트(Release Note)란 소프트웨어 또는 서비스가 출시 또는 업데이트 될 때마다 해당 상품의 배포와 함께 변경 사항, 기능 추가/삭제, 버그 개선 등 변경 사항을 체계적으로 정리하여 정보를 제공하는 문서입니다. 릴리즈 노트는 종이 매뉴얼, 모바일/웹 애플리케이션, 개발자 사이트 등 다양한 소스에 게시될 수 있습니다.

이러한 릴리즈 노트는 언제부터 작성하게 되었을까요? 인터넷이 발달하기 이전에는 소프트웨어 유통을 위해 플로피 디스크나 CD 등의 물리적인 매개체가 필요했습니다. 그렇다 보니 이미 출시하고 판매된 소프트웨어에 대한 업데이트나 수정이 매우 어려웠죠. 하지만 지금은 대부분의 소프트웨어, 플랫폼, 애플리케이션 등의 서비스가 온라인을 통해 유통되면서 지속적으로 사용자들로부터 피드백을 받고 이를 반영하여 업데이트 및 재배포가 가능해졌습니다. 이렇게 제품 혹은 서비스가 지속적으로 변화하게 되면서 업데이트와 수정 사항을 기록하고, 이를 내·외부적으로 공유해야 할 필요성이 제기되어 많은 회사들이 릴리즈 노트를 작성하게 되었습니다.

[그림 1]  릴리즈 노트 사례 (Microsoft Docs, Google Cloud, 카카오 i 기술문서)

릴리즈 노트는 정보 공유뿐만 아니라 우리 회사에 대한 긍정적인 인상을 심어주는 중요한 역할을 하는데요. 릴리즈 노트가 꼭 작성되고 공유되어야 하는 이유는 다음과 같습니다.

✔️ 업데이트 정보를 한데 모아 기록함으로써, 내가 작업하지 않은 업데이트 사항도 빠르게 파악 가능
✔️ 릴리즈 노트를 보면 누구나 제품의 발자취를 한눈에 파악 가능
✔️ 우리 회사의 제품 혹은 서비스가 지속적으로 개선되고 최신의 상태를 유지하고 있음을 안내
✔️ 사용자의 신고와 의견을 반영하고 있다는 인상을 주어 사용자의 적극적인 피드백을 유도

릴리즈 노트가 중요한 이유는 이렇게 많지만, 릴리즈 노트를 작성하려면 나름의 형식을 갖춰야 하고 지속적인 작성과 관리가 필요하므로 귀찮고 어렵다고 느끼시는 분들도 많으신데요. 이어서 릴리즈 노트의 구성요소와 작성 Tip을 통해 릴리즈 노트에 좀 더 가까이 다가가 보도록 하겠습니다.

릴리즈 노트의 구성 요소

릴리즈 노트의 구성 요소에는 어떤 항목들이 있을까요? 사실 회사나 조직마다 준수해야 하는 릴리즈 노트 표준은 존재하지 않지만, 일반적으로 릴리즈 노트는 버전, 날짜, 구분, 설명으로 구성됩니다. 그럼 각 항목을 자세히 살펴보겠습니다.

① 버전

우리는 매일 모바일과 PC에서 다양한 버전의 애플리케이션을 사용하고 있는데요. 이 애플리케이션들은 보통 알파(Alpha), 베타(Beta), 출시 후보(Release Candidate), 출시(Release)로 구성된 소프트웨어 배포 생명 주기를 거치게 됩니다. 내부 개발 단계에서는 다양한 소프트웨어 버전이 존재할 수 있지만, 저희 카카오 i 기술문서에서 릴리즈 노트는 제품 출시 시점에 맞춰 V.1.0.0부터 시작하며, 이후 발생하는 변경 사항은 마이너 버전 업데이트(소수점 둘째 자리), 패치 업데이트(소수점 셋째 자리)로 구분하여 버전을 업데이트합니다.

위의 표와 같이 소프트웨어 버전 구분은 소프트웨어 버전 관리에서 널리 통용되는 규칙으로서 릴리즈 노트의 버전 규칙에도 적용할 수 있는데요. 독자들은 릴리즈 노트의 버전 정보를 보고 "이번에는 대대적인 변화가 있었구나", "신규 기능이 추가되었군", "이번 버전에는 큰 업데이트는 없고 Bug Fix만 있네" 등 해당 소프트웨어의 변경 범위를 대략적으로 유추할 수 있게 됩니다.

② 날짜

릴리즈 노트에는 버전 출시나 문서 업데이트에 따른 날짜 정보가 포함되며, 날짜는 해당 문서가 얼마나 최신인지 보여주는 역할을 합니다. 날짜를 표기할 때는 영어식 표기 또는 국어식 표기 중 하나의 스타일을 정하고 전체 문서에서 일관된 스타일을 유지하는 것이 중요한데요. 작업자마다 또는 문서마다 날짜 형식을 다르게 쓰는 상황이 많이 발생하기 때문에, Google 또는 Amazon 등의 글로벌 IT 회사들의 스타일 가이드에서는 날짜 표기 방식에 대해 구체적으로 정의를 하고 있습니다. Google의 스타일 가이드를 보면 가능하면 월(Month)을 알파벳으로 풀어쓰고, 숫자로만 날짜를 표기해야 할 경우에는 하이픈(-)을 사용하고, 슬래시(/)는 사용하지 말 것 등의 구체적 용례를 제시하고 있습니다.

[그림 3] 날짜 (Microsoft Docs, Google Cloud, 카카오 i 기술문서)

③ 구분

구분은 사용자들에게 해당 기능이 신규 추가 항목인지 또는 수정 항목인지등의 변경 사항을 빠르게 파악할 수 있도록 도와주는 태그(Tag) 역할을 합니다. 구분이 없다면 독자는 자신이 찾는 변경점을 찾기 위해 내용을 일일이 다 확인하기 때문에 구분을 통해 변경 사항을 표시하면 독자는 본인이 원하는 항목을 보다 쉽게 찾을 수 있습니다.

Google, Amazon 등의 기술 문서에서도 이런 구분을 사용하는데요. 일반적으로 New(최초), Feature(기능), Changed(변경), Fixed(수정), Deprecated(중단) 등의 항목이 포함될 수 있습니다. 카카오 i 기술문서에서도 이런 태그를 사용하여 독자가 쉽게 변경사항을 파악할 수 있도록 하고 있습니다.

④ 설명

설명은 소프트웨어의 변경사항을 기술하는 부분인데요. 상품이나 서비스의 특성에 따라 릴리즈 노트의 설명 부분이 한 줄로 간략하게 끝날 수도 있고, 자세하게 풀어 쓰는 것도 가능합니다. 하지만 릴리즈 노트는 간략하고 집약적으로 작성하는 것이 일반적이기 때문에 만약 해당 항목의 변경 사항을 자세히 안내하고 싶은 경우에는 관련 문서 링크를 연결하는 것이 좋습니다. 카카오 i 기술문서 사이트의 경우, 설명은 개조식(글을 쓸 때 짧게 끊어서 중요한 요점이나 단어를 나열하는 방식), 키워드는 굵기 표시(Bold) 스타일을 적용하고 있으며, 관련 챕터를 링크로 연결하는 방식을 적용하고 있습니다.

릴리즈 노트 작성 Tip

이제 릴리즈 노트를 작성하기 위한 Tip을 살펴보도록 하겠습니다.

① "버그 수정 및 성능 개선"은 이제 그만!

이번 포스팅을 쓰면서 릴리즈 노트에 대한 한 칼럼(출처: iMore)을 보게 되었는데요. 많은 개발자들이 릴리즈 노트를 쓸 때 "Bug Fixes and Improvements(버그 수정 및 성능 개선)"라는 문구만을 반복적으로 사용하고 있다며, 이런 릴리즈 노트 작성 방식을 지양해야 한다는 내용을 담고 있었습니다.

물론 릴리즈 노트를 아주 길고 상세하게 적을 필요는 없지만, 적어도 ‘어떤' 버그가 개선되었는지, ‘어떤' 기능이 ‘어떻게’ 변경되거나 추가되었는지는 사용자가 파악할 수 있도록 작성하는 것이 좋습니다. 릴리즈 노트를 즐겨 읽고 개선된 기능을 빨리 사용해 보고 싶어 하는 독자들에게 알맞은 정보를 전달해 주어야 할 것입니다.

② 짧게 작성하고, 링크를 활용하라

릴리즈 노트는 최대한 간결하게 작성하는 게 좋습니다. 릴리즈 노트의 항목들이 두 줄을 넘어가게 되면, 고객들은 릴리즈 노트가 아닌 매뉴얼 본문을 보는 듯한 착각에 빠질 수 있습니다. 릴리즈 노트의 목적은 간결하고 집약적으로 해당 소프트웨어/서비스의 변경 사항을 보여주는 것이기 때문에, 문장 길이가 길어지면 오히려 가독성이 저하될 수 있습니다. 만약 고객에게 해당 항목에 대한 자세한 설명을 안내하고 싶다면, 관련 문서 페이지의 링크를 안내하는 것이 좋습니다.

③ 일관된 용어를 사용하라

개발자들과 테크니컬라이터들이 문서를 작업하다 보면 작업자마다 사용하는 용어가 다른 경우가 존재합니다. 예를 들어 ‘BOT Response 기능 추가’, ‘Bot 응답 개선’, ‘봇의 응답 방식 개선’ 등 동일한 용어 또는 기능을 각기 다른 방식으로 표현하는 경우가 많은데요. 내부 작업자들 간 소통에 있어서는 어느 정도 소통이 가능하겠지만, 사용자 입장에서는 ‘이게 동일 기능인가?’하고 혼란스러울 수 있습니다. 일관된 용어의 사용은 기술문서의 대원칙이기도 하지만 릴리즈 노트를 작성할 때에도 혹시 동일한 용어를 다른 표현으로 사용하고 있지는 않은지 확인해야 합니다.

④ 사용자 관점에서 쉽게 작성하라

릴리즈 노트는 사용자(독자)를 위한 문서이기 때문에 사용자 관점에서 작성해야 하며, 사용자가 어떤 부분이 추가, 삭제, 수정 등이 되었는지 쉽게 파악할 수 있도록 해야 합니다. 예를 들어 ‘BEAN 설정 추가’라고 쓰는 것보다는 ‘설정 메뉴에 BEAN 설정 추가 사용 가능’과 같이 사용자가 주어라고 생각하고 글을 작성하는 것이 가독성을 높일 수 있습니다.

⑤ 시각적 효과(그룹화)를 적용하라

많은 사용자들은 릴리즈 노트를 읽을 때 ‘자신이 제보한 버그가 수정되었는지(Fixed)’, ‘이번 버전에서는 신규 기능이 있는지(New)’ 등의 특정 목적을 가지고 릴리즈 노트를 읽는데요. 같은 내용이라도 색을 활용하여 구분을 나타내고 여백 또는 구분선 등을 활용하여 섹션을 구분하는 등 시각적 효과를 적용하면 릴리즈 노트의 가독성을 개선할 수 있습니다. 또한 논리적으로 비슷한 항목들을 그룹화하여 나열하면 더욱 깔끔한 릴리즈 노트를 구성할 수 있습니다.

마치며

최근 몇 년간 기술문서가 종이에서 온라인으로 자리를 급격하게 옮겨가면서, IT 회사들의 릴리즈 노트 게시 방식이나 스타일에도 큰 변화가 생겼습니다. 초기 온라인상에 게시된 릴리즈 노트는 밋밋한 문서에 변경점에 대한 끝없는 나열에 불과했다면, 최근 트렌드는 시각적 효과, 그룹화, 링크 연결을 통해 스타일리쉬한 릴리즈 노트로 변모하고 있는 것 같습니다. 앞으로 릴리즈 노트는 어떻게 더 변화하고 발전해 나갈까요? 개인적으로는 Android Studio처럼 영상을 통해 릴리즈 노트의 업데이트된 기능을 시연해 주는 것이 새로운 트렌드로 자리 잡지 않을까 조심스럽게 추측해 봅니다.

여담으로, Google은 2017년부터 Google Play Store에 신규 앱이 출시될 때 개발자들에게 릴리즈 노트를 반드시 추가하도록 Release Note 섹션을 만들어 개발자들에게 작성을 권고하고 있는데요. 안타깝게도 많은 개발자들은 릴리즈 노트 섹션에 “Bug Fixes and Improvements”라고만 적고 있다고 합니다.

여러분들은 릴리즈 노트를 어떻게 적고 계신가요? 혹시 "버그 수정 및 기능 개선"이라고 적고 계시지는 않을까요? 릴리즈 노트는 더 이상 구색 맞추기 식의 항목이 아니며, 독자나 외부 개발자들에게 우리 회사의 상품/서비스의 업데이트 상황을 정확하고 가장 효율적으로 전달할 수 있는 문서라는 점을 잊지 말아야 할 것입니다.
그럼 다음 시간에는 더욱 재미있고 알찬 톺아보기 시리즈로 돌아오겠습니다.