호주 오프라인 컨퍼런스는 가을 정도에 개최를 하는데 Virtual 이벤트라고 영상이 올라왔더라구요. 찾아보니, 이전에도 간혹 진행했던 행사인 모양입니다. 이번에는 idratherbewriting.com 블로그 운영자로 잘 알려진 Tom Johnson의 발표입니다. 블로그를 구독하거나 간혹 보시는 분들은 최근 AI 관련해서 올라오는 그의 글을 이미 보았을 겁니다.
참고
발표 슬라이드와 원본 블로그, 관련 영상을 참고할 수 있습니다.
슬라이드
https://idbwrtng.com/releasenoteswithai
(블로그) Using file diffs for better release notes in reference docs
https://idratherbewriting.com/ai/prompt-engineering-release-notes-reference-docs.html
(영상) Using file diffs for better release notes in reference docs
https://youtu.be/bzreBdnxObI?si=LSKRejXFv6_yBODv
아래 내용은 생각나는 대로 정리한 것이기 때문에 참고로만 확인하세요.
일반적으로 릴리스 노트를 작성하는 프로세스는 아래와 같습니다.
1. Release team provides launch entry and tries to get input from eng team
릴리스 담당자가 출시 대상 항목을 제공하고 담당 엔지니어의 피드백을 받습니다.
2. TW reaches out to engineers to add notes to a staging doc
테크니컬 라이터는 담당 엔지니어에게 연락해 스테이징 문서를 보완합니다.
3. TW sees lots of file changes with no notes; much of the eng input is opaque
테크니컬 라이터는 변경 내역이 기재되어 있지 않은 파일 변경 사항을 확인합니다. 일부 작성된 변경 내역도 명확하지 않습니다.
4. Lots of back and forth to gather info, verify
정보를 수집하고 확인하기 위해 많은 의사소통이 오고 갑니다.
전통적인 소프트웨어 배포 주기에서는 이런 프로세스를 어느 정도 견딜 수 있습니다. 하지만 배포 주기가 2주일, 1주일 또는 그 보다 짧게 진행된다면 이런 릴리스 노트 프로세스를 유지하는 것이 쉽지 않습니다.
그리고 엔지니어가 릴리스에 포함되는 변경 사항을 모두 기억하고 테크니컬 라이터에게 이야기해 주는 것이 아니기 때문에 항상 무언가 누락되는 건이 발생합니다.
발표자가 제안하는 새로운 프로세스는 AI를 사용해 파일의 변경 사항을 확인하고 이를 정리한 자료를 생성하는 것입니다. 좀 더 상세하게 들어가면 다음과 같은 프로세스입니다. API 참조 문서에 대한 것이구요. 기본적인 API 참조 문서는 코드 기반으로 생성된다는 전제로 설명합니다. 코드 자체를 비교하는 것이 아니라 코드에서 생성된 API 문서 각각의 파일을 비교하는 것이네요.
(좀 애매하긴 한데 블로그 글을 보면 코드의 변경 사항은 생성된 참조 문서에 반영이 된다고 설명하고 있습니다. 기능 변경이나 신규 기능인 경우에는 그렇긴 하겠지만 버그를 수정하거나 하는 변경 사항은 반영이 되지 않을 겁니다. 일반적으로 릴리스 노트에는 수정 사항에 대해서도 언급을 하고 있는데 아마 발표자가 이야기하는 것은 신규, 변경에 한정된 것이 아닌가 싶긴 합니다.
Note that I’m specifically referring to the documentation changelist, not the source code CLs. For example, you don’t need to access changelists related to Java files or proto files. Reason being, all the changes to the source code almost always end up impacting the generated documentation. An engineer can rarely change some aspect of the source and not have that change ripple through to the reference documentation).
1. Build the API reference output.
코드로부터 API 레퍼런스 문서를 생성하고
2. Get file diffs for each file changed in the regenerated reference.
이전 문서와 비교해 변경된 항목 목록을 작성합니다.
(버전 관리 시스템에서 기본 제공하는 기능을 사용합니다).
3. Use Al to get readable summaries for each diff.
AI에서 변경된 항목에 대한 요약을 작성하고
(뭔가 프로세스를 통해 진행하는 것이라 생각했는데, 변경 정보를 복사해서 AI 도구에 붙여 넣고 쓰는 형식이네요. 프롬프트 예시는 아래 링크에서 확인할 수 있습니다.
https://idratherbewriting.com/ai/prompt-engineering-release-notes-reference-docs.html#step-3-get-human-readable-summaries-of-the-file-diffs
프롬프트를 보면 요약이라기보다는 diff 결과물을 테크니컬 라이터가 이해할 수 있게 풀어서 설명해 달라는 요청 정도가 적절하겠네요).
(물론 이 과정에서 실제 코드 변경 사항이 AI 도구에 전달될 수 있기 때문에 조직의 보안 정책에 따라 주의해야 합니다).
4. Use Al to organize all readable summaries.
모든 변경 사항에 대한 요약을 정리합니다.
(각 diff 결과물을 정리하면 일부는 중복된 내용도 있을 수 있습니다. 예를 들어 같은 변경인데 적용되는 버전만 다른 경우에는 하나로 묶어서 설명할 수 있겠죠. 이런 내용을 그룹으로 만들거나 정리하는 것입니다).
5. Edit, restructure, analyze, fix, etc.
테크니컬 라이터는 요약 문서를 확인하고
(AI가 최종 결과물을 만들어주는 것이 아니고 초안을 만들어준다고 생각해야 합니다. 테크니컬 라이터가 할 일이 아예 없어지는 건 아니죠).
6. Link every code element to its reference source and verify.
실제 변경된 내용인지 검토한 후에
(각 항목에 대해 실제 코드 요소에 대한 링크를 작성하고 변경 여부를 확인합니다. AI 도구 사용 시 환각 hallucination으로 인해 잘못된 정보가 만들어질 수 있고 이를 검토하는 것은 테크니컬 라이터의 역할입니다).
7. Check whether updates affect other documentation.
다른 문서에 영향이 있는지 확인하고
8. Review with engineers.
담당 엔지니어의 피드백을 받습니다.
AI가 생성하는 정보는 사실 기반으로 작성하기 때문에 어떤 사건에 대한 배경까지 설명하지는 못합니다. 예를 들어 특정 함수를 더 이상 지원하지 않아 삭제했다고 하면 AI 요약은 그냥 삭제되었다고만 알려주겠죠. 하지만 사용자에게는 왜 어떤 이유로 그 함수를 더 이상 지원하지 않는지 설명해주어야 합니다.
(간혹 엔지니어가 실수로 잘못된 함수를 만들었고 이를 삭제하는 경우가 있습니다. 이럴 때 릴리스 노트에서는 개발자의 실수라고 그대로 언급하기는 어렵죠. 이럴 때는 테크니컬 라이터가 지혜롭게 코드를 간소화하고 효율적으로 변경했습니다 정도로 릴리스 노트를 작성할 수 있습니다).
AI가 많은 일을 해주고 엔지니어와의 커뮤니케이션이 많이 줄어들었다고 하더라도 엔지니어와의 관계를 적절하게 유지하는 것은 중요합니다. AI는 엔지니어가 제대로 이야기해주지 못하거나 놓칠 수 있는 부분을 보완해 주는 역할이라고 볼 수도 있습니다. 그동안 엔지니어가 알려주지 않는 변경 때문에 사용자가 문서를 신뢰하지 않았던 것을 어느 정도 보완해 준다고 할 수 있죠.
릴리스 노트가 주요 변경사항을 제대로 다루어줄 수 있다면 오히려 제품 관리자도 릴리스를 검토하는 과정에 릴리스 노트 문서를 참조할 수 있습니다. 그리고 그만큼 테크니컬 라이터가 제품 프로세스에서 중요한 역할을 맡게 될 수 있습니다.
https://youtu.be/bzreBdnxObI?si=LSKRejXFv6_yBODv
