릴리즈 노트란? 그리고 작성하는 방법과 Tip

특히 Git 오픈소스에서 릴리즈 노트를 쉽게 볼 수 있다.

사용자 입장에서 간결하고 핵심만 정리된 릴리즈 노트는 해당 버전에서의 수정된 사항을 바탕으로 업데이트된 버전 이용 여부를 판단하는데 도움을 준다.

 

Release Note
: 소프트웨어의 업데이트 때마다 개선 사항과 추가 기능들을 요약한 문서

 

 

---

 

릴리즈 노트 구성 요소

 

1. 버전

https://tech.kakaoenterprise.com/113

 

 

2. 날짜

• Google의 스타일 가이드에서는 가능하면 월(month)를 단어로 쓰고,
• 숫자로만 표시해야하는 경우에는 하이픈을 사용해야한다는 가이드가 있다.

ex) June 15, 2021  /  2021-08-18

 

 

3. 구분 (Tag)

해당 태그를 제공하면 신규인지 수정인지 빠르게 구분이 가능하다.

https://tech.kakaoenterprise.com/113

위의 표 외에도

• Know issues: 간헐적 또는 자주 발생하는 오류를 인지하고 있다는 것을 알려주는 경우 (아직 고치지 못함)

 

 

예시

https://tech.kakaoenterprise.com/113

 

4. 설명

한줄로 간략히 작성하며, 자세히 설명할 부분은 관련 문서를 링크하는 것이 좋다.

 

---

 

기타 Tip

• "버그 수정 및 수정 개선" 이라는 문장을 그만 사용하고, 구체적으로 어떤 버그가 어떻게 변경되었는지 작성하기
• 짧게 작성하고 링크를 활용하기
• 일관된 용어, 단어를 사용하기 (사용자 입장에서는 서로 다른 기능으로 오해할 수 있다)
• 사용자 관점에서 or 초보 개발자도 이해할 수 있게 작성하기
• 태그 같은 요소의 색을 구분하거나 구분선 등 시각적 효과를 활용해서 가독성 높이기
• "Expand out and Simplify" 설명을 작성할 때 처음 부터 간결하게 쓰도록 노력하는 것보다 길더라도 정보를 정확하게 적는데 중요하고, 그 뒤에 중요하지 않은 부분들을 제거하면서 간결화하기
• 유머나 개성이 드러나는 글은 지양하기

 

문장 예시

• fix, feature 항목에 대한 설명:
  • ~을 할 수 있음 / ~이 가능해짐
• 과거와 현재의 차이를 설명:
  • Z일 때 Y하지 않고 X하게 됨
• 과거대신 현재를 수행하여 목표을 이룰 수 있도록 가이드:
  • Z를 하기 위해 Y대신 X를 해야함

 

---

 

참고

 

Release Note 톺아보기

 

테크니컬 라이팅 컨퍼런스: Write the Docs Prague 2018 방문기