Using AI to create doc updates based on bugs 라는 문서에 대한 번역입니다. 개인적인 학습 용도이며, 아마도 이 글을 보는 것보다 이 글을 작성한 시점보다 좀 더 나아진 기계번역의 힘을 빌리는 것이 좀 더 좋은 방법이라 생각됩니다.
https://idratherbewriting.com/learnapidoc/docapis_ai_fix_bugs.html
Using AI to create doc updates based on bugs
Download PDF
idratherbewriting.com
저는 사용자가 등록한 버그를 상시 확인하고 문서를 업데이트합니다. 이런 작업은 새로운 기능에 대한 문서를 작성하는 것이 아니라 이미 공개된 문서에 대한 수정이 필요한 상태입니다.
예를 들면, 사용자가 API의 특정 필드에서 반환되는 값이 이상하다는 피드백을 제공하는 일반적인 시나리오입니다. 사용자는 버그를 제출하고 담당 엔지니어와 의견을 주고받기 시작합니다. 개발팀에서 해당 문제를 수정하거나 보완할 수 있습니다. 그리고 다음 단계로 엔지니어는 테크니컬 라이터가 문서를 업데이트할 수 있게 문서 수정 요청을 작성합니다. 절차는 정말 간단합니다. 하지만 보통은 간단하게 처리되지 않습니다.
문서 수정 요청 절차
실제 수정할 문서의 내용은 몇 줄 안 될 수도 있습니다. 문서 수정 요청의 일반적인 절차는 다음과 같습니다.
- 사용자가 제품 팀(또는 관련 개발 팀)과 미팅 중에 API 관련 문제를 제기합니다. 회의록에는 문제가 간략하게 설명되어 있어 회의에 참석하지 않았다면 관련 문제가 어떤 맥락에서 제기된 것인지 명확하게 알 수 없습니다.
- 회의록에는 티켓에 작업 항목을 기록하겠다고 했지만 실제 티켓에는 간단한 논의 내용만 기재되어 있습니다. 프로젝트에 관련된 이들은 해당 이슈를 어느 정도 알고 있다고 가정하기 때문에 세부 정보를 추가하지 않습니다.
- 티켓에 대한 설명에는 보통 12개 이상의 댓글이 달립니다. 요구사항에 대한 최초 설명이 구현 과정에서 변경되거나 추가되는 경우가 많기 때문입니다. 일부 버그는 댓글이 너무 많아 이를 읽는데 최소 1시간 이상이 걸리기도 합니다. 정말 지독한 버그인 경우에는 다른 댓글로 연결되는 수십여 개의 댓글이 있을 수도 있습니다. 또는 관련 이메일 스레드가 추가되기도 합니다. 이런 스레드는 서로 다른 해결책과 견해가 혼잡스럽게 섞여 있습니다.
- 티켓 설명이나 스레드에서 실제 문제가 무엇이고 해결 방법이 어떤 것인지, 어떤 문서가 업데이트되어야 하는지 명확하게 드러나지 않습니다. 운이 좋다면 티켓에 코드 변경 사항이 첨부되어 있을 수도 있지만 코드를 보고 어떤 문제가 해결된 것인지 명확하게 이해하기 어려울 수도 있습니다. 여러분이 티켓을 검토하는 중에 누군가 버그를 수정하고 티켓을 종료할 수도 있습니다. 실제 수정 사항을 설명하는 댓글이 있다면 어떤 댓글인지 직접 찾아야 합니다. 테크니컬 라이터가 참여하지 않는 회의(예를 들어 일일 스탠드업 미팅)에서 티켓 해결 방법에 대해 논의되고 이를 기록하지 않았을 수도 있습니다.
- 제품 팀은 사용자에게 전화, 채팅, 미팅, 이메일 등을 통해 수정 사항을 전달합니다.
- 문제를 처리한 개발자는 테크니컬 라이터가 문서를 수정할 수 있게 요구 사항을 등록합니다. 하지만 개발자는 너무 바빠서 티켓의 설명을 읽기 쉽게 수정하거나 내용을 보완하는 것에 관심이 없습니다. 문서 수정 요청의 내용은 모호하게 작성되어 있으며 자세한 문제와 수정 사항은 티켓을 참고하라고 합니다.
- 테크니컬 라이터는 작업 목록에 티켓을 올려놓고 문서의 어떤 내용이 수정되어야 하는지 확인하기 위해 티켓 본문과 관련 스레드를 검토하기 위해 많은 시간을 들여야 합니다.
- 티켓 내용을 모두 검토했지만 여전히 모호한 부분이 있어 제품 팀에 문의하고 피드백을 받습니다.
- 개발자는 다른 작업을 진행하고 있기 때문에 테크니컬 라이터의 질문에 답변하는데 많은 시간을 쓸 수 없습니다. 티켓 본문과 관련 스레드를 보면 다 알 수 있는 거 아닌가요?
- 테크니컬 라이터는 티켓 본문과 스레드를 검토하고 담당 개발자의 피드백을 확인한 후에 문서를 수정하고 문서 변경에 대한 리뷰를 요청합니다.
- 최종적으로 문서 변경 내용을 승인하고 게시하기 전에 테크니컬 라이터가 작성한 내용에 대해 제품 팀과 피드백을 주고받는 작업이 진행됩니다.
이런 절차가 익숙하다면 여러분도 저와 다르지 않네요. 버그로 인한 문서 업데이트는 그리 반갑지 않은 작업입니다. 버그를 기반으로 필요한 문서 수정 목록을 작성했다가 얼마 지나지 않아 포기한 적이 몇 번이나 있는지 모를 정도입니다. 이런 작업은 지루하고 마감 기한이 정해져 있지 않은 경우가 많습니다.
개발자는 버그를 해결하고 나면 다른 작업으로 넘어갑니다. 누군가 버그에 대한 질문을 하면 개발자도 다시 티켓을 살펴봐야 합니다. 일반적으로 버그를 등록한 사용자에게는 버그 수정에 대한 알림이 전달되고 아무도 해결된 버그에 대한 추가적인 의견을 제기하지 않기 때문에 관련 문서 수정은 우선순위가 밀리게 됩니다. 또한 테크니컬 라이터 역시 기존 코드의 버그 수정보다는 다음 릴리스를 위한 문서화에 대부분 에너지를 집중해야 합니다.
수 천 개의 작은 수정을 통해 훌륭한 사용자 경험 만들기
다음 릴리스 문서 작업 때문에 수정된 버그에 대한 문서 업데이트를 하지 못하는 것에 대해 누구 못지않게 죄책감을 느낍니다. 그런데 지난주에 버그에 대한 흥미로운 아이디어가 떠올랐습니다. 어느 날 오후 지원팀에서 어떤 작업에 포커스를 맞추고 있는지 알고 싶어서 티켓 시스템에 접수된 모든 버그를 살펴보기 시작했습니다. 티켓을 읽어보니 지원팀에서는 등록된 수많은 제품의 소소한 버그의 원인과 수정 방법을 조사하고 있다는 것을 알 수 있었습니다. 지원팀의 업무 범위는 문제 해결 방안을 찾고 버그를 수정하고 제품 팀과의 사용자와의 인터페이스 역할을 하고 있었습니다.
이를 살펴보면서 깨달음을 얻었습니다. 제품을 훌륭하게 만드는 것이 어떤 큰 기능이 아니라 사용자가 발견한 수 천 개의 작은 버그를 수정하는 것이 아닐까요? 그리고 수 천 개의 버그를 수정해 제품의 우수성을 확보할 수 있다면 문서도 같은 방식으로 향상될 수 있지 않을까요? 사용자가 보고한 수천 개의 작은 버그에 대해 테크니컬 라이터가 관심을 가지고 문서의 우수성을 획득할 수 있다면 어떨까요? 하나의 문장, 하나의 용어 정의, 하나의 개념 정의 등을 수정하면서 수 천 개의 버그에 대한 문서 수정이 쌓이면 진정으로 다음 단계로 나아갈 수 있는 겁니다.
수 천 개의 작은 수정이 훌륭한 사용자 경험으로 가는 길을 열어준다면 버그를 인지하는데 그치지 않고 정기적으로 버그를 분류하고 수정할 수 있는 훨씬 더 나은 시스템을 개발해야 합니다. 버그를 기반으로 문서를 업데이트하는 더 나은 시스템이 필요하다는 겁니다.
AI의 도움을 받아 버그 확인하기
버그를 기반으로 문서를 업데이트하는 데 AI가 도움을 줄 수 있나요? 네. 그렇게 생각합니다. 제가 특히 기대하는 기능입니다. 이제 막 사용해 보기 시작했다는 점을 참고해 주세요. AI를 사용해 버그를 해결하는 일반적인 접근 방식은 다음과 같습니다.
먼저 버그와 관련된 모든 관련 정보, 회의록, 코드 변경 사항, 논의된 모든 스레드를 구글 문서에 복사합니다.
그런 다음 수집한 콘텐츠를 입력 소스로 대량 데이터를 처리할 수 있는 AI 도구를 사용합니다. 사용할 수 있는 도구는 Claude.ai와 NotebookLM이 있습니다. 다른 AI 도구도 유용할 수 있습니다. AI 도구를 사용할 때는 서비스 제공자의 데이터 정책을 고려하세요. 우리는 데이터 기밀성 때문에 NotebookLM을 사용하고 있습니다.
claude.ai는 약 175페이지 분량의 데이터를 처리할 수 있다고 합니다. 미국과 영국에서만 서비스를 제공합니다.
NotebookLM의 경우 아직 정식 서비스를 제공하지 않고 있으며 대기 리스트도 미국만 지원합니다.
수집한 콘텐츠를 입력한 후 AI에게 다음과 같이 질문하세요.
Based on the input sources, provide a summary of the issue {about ...} and the resolution taken to fix the issue.
입력한 소스 데이터를 기반으로 {~에 대한} 문제를 요약하고 문제 해결 방안이 어떻게 결정되었는지 알려줘.
원하는 답변의 패턴을 제공할 수 있다면 좀 더 정확한 결과를 얻을 수 있습니다. 예를 들어 릴리스 노트를 데이터로 사용하는 경우에는 다음과 같이 수정 사항을 설명할 수 있습니다.
A bug related to [X feature] was fixed. Previously, [X feature] was doing [Y]. The [X feature] was updated to produce [Z]. For more details, see [X feature].
[기능 X] 관련 버그가 수정됐습니다. 이전 버전에서는 [기능 X]는 [Y]로 동작했습니다. 버그 수정으로 인해 [기능 X]는 [Z]를 생성하도록 업데이트됐습니다. 좀 더 자세한 내용은 [기능 X]를 참고하세요.
아직 이런저런 방향으로 실험하고 있는 중이라 프롬프트에 대한 정확한 답은 찾지 못했습니다만 패턴 형식은 도움이 되었습니다. 경험상 AI의 요약과 기타 설명을 통해 버그를 올바르게 해석할 수 있는 확신이 들었습니다. 또한 AI가 요약한 문장이 이해되지 않은 경우 간단한 설명을 요청할 수도 있습니다.
AI가 릴리스 노트나 다른 형식의 멋진 요약과 해결책을 제공하더라도 테크니컬 라이터의 확인이 필요하다는 점을 유의해주세요. 또한 문서에서 업데이트되어야 하는 지점을 확인한 후에 기존에 작성된 문장의 맥락에 따라 매끄럽게 새로운 내용을 추가하거나 수정해야 합니다. AI 도구가 이 모든 것을 대신해 줄 수는 없습니다. 여러 페이지 문서를 업데이트해야 할 수도 있습니다. 업데이트가 필요한 모든 항목을 검색하고 변경된 목록을 개발자가 검토할 수 있도록 공유하는 작업을 진행하려면 시간이 많이 소요될 수도 있습니다.
여전히 문서를 수정하는데 많은 시간이 필요하지만 AI가 회의록과 관련 자료를 확인하고 어떤 버그인지 분석하고 해석해 주는 작업을 일부 대신해 주면서 불필요한 시간 낭비를 줄일 수 있었습니다.
앞에서 언급했듯이 이런 기술은 아직 실험 중입니다. 그럼에도 AI를 사용해 버그를 좀 더 빨리 수정할 수 있다면 버그 수정과 관련된 프로세스가 더 빠르고 덜 고통스러워질 수 있다는 것은 명백한 사실입니다. 기존 작업 시간보다 50% 정도만 줄일 수 있어도 큰 성과가 될 것입니다.
버그 수정 경험 및 몇 가지 위험 사항
최근에 까다로운 버그를 처리하면서 입력할 콘텐츠를 조정해야 한다는 사실을 발견했습니다. 해당 버그에는 관련 엔지니어링 문서가 연결되어 있었습니다. 이런 문서의 전형적인 유형은 문제를 정의하고 제안된 해결책을 제시한 다음 몇 가지 대체 솔루션을 제시합니다. 저는 엔지니어에게 연락해 실제 어떤 방식이 취해졌는지, 어떤 부분이 향후 개선되어야 할 부분인지, 어떤 부분이 구현된 콘텐츠인지 확인해야 했습니다. 해당 콘텐츠를 AI에 입력 데이터로 전달하기 전에 AI 응답에 혼란을 줄 수 있는 대체 솔루션과 향후 개선될 부분에 대한 내용은 제거했습니다.
또한 앞에서 설명한 버그의 모든 특징을 가지고 있었습니다. 개념은 매우 기술적이고 이해하기 어려웠습니다. 그래서 AI에게 용어를 정의하고 개념을 명확히 하고, 설명을 단순화해 달라고 반복해서 요청했습니다. AI의 답변을 읽으면서 내용이 적절한지 확인했습니다.
AI가 생성한 설명을 완전히 믿을 수는 없기 때문에 이를 체크하기 위해 엔지니어링 티켓, 문서, 이메일 스레드 등을 꼼꼼하게 살펴보았습니다. 그리고 제품 팀과 필요한 대화를 나누기도 했습니다. 이렇게까지 해야 한다면 AI를 사용하는 이유가 뭐냐고 생각할 수도 있겠죠? 중요한 것은 AI 덕분에 모든 것이 훨씬 더 이해하기 쉬워졌다는 것입니다.
좀 쉽게 예를 들어보죠. 기술적인 문제가 아니라 미적분 관련 버그를 다루게 되어 몇 가지 방정식과 팀에서 어떻게 처리했는지 설명해야 한다고 가정해 보죠. 여러분은 미적분을 배운 지 25년 이상 지났기 때문에 엔지니어가 아무리 설명해도 무슨 말인지 이해하기 어려울 겁니다. 전문 용어, 필요한 배경 지식, 세부 사항이 너무 많아서 제대로 공부하지 않으면 내용을 이해하기 어렵습니다.
하지만 AI가 낯선 용어를 정의하고 설명을 단순화하고 예제를 제공하고 원하는 만큼 반복해서 설명해 주면서 수학 콘텐츠를 더 읽기 쉽게 만들 수 있다면 어떨까요? 이런 식으로 AI는 여러분에게 과외 선생님이 되어 좀 더 효율적으로 수학 관련 문제를 이해할 수 있게 도와줍니다.
점점 더 많은 사람들이 이런 방식으로 AI를 사용하고 있습니다. 물론 AI가 일부 콘텐츠의 초안을 작성하고 이를 복사해 엔지니어와 공유하고 검토할 수도 있습니다. 하지만 이런 프로세스는 확장성이 떨어집니다. 단기적으로는 이득이 될 수 있지만 장기적으로는 생산성이 저하됩니다. 테크니컬 라이터는 자신이 문서화하는 제품의 문제와 해결책을 최소한 기본적으로 이해하는 것이 중요합니다. 이런 지식은 다른 문서를 작업할 때 도움이 됩니다.
예를 들어 어떤 버그의 문제를 이해하면 다른 문서 영역에 대한 이해의 폭을 넓힐 수 있고 확장하거나 추가 설명이 필요한 콘텐츠에 대한 인식을 높일 수 있습니다. 테크니컬 라이터가 AI가 작성한 내용을 무턱대고 복사해 붙여 넣기만 하고 엔지니어에게 검토를 맡긴다면 이런 인사이트는 전혀 얻을 수 없습니다. 하지만 테크니컬 라이터가 AI가 작성한 콘텐츠를 일종의 요약문으로 활용해 긴 셰익스피어 작품을 이해한다면 하나의 버그를 수정하는 데 며칠을 소비하지 않고도 충분한 학습을 할 수 있는 실용적이고 효율적인 방법이 될 수 있습니다.
또 다른 위험: 제대로 보지 않고 승인하기
엔지니어와 제품 팀원에게 AI가 작성한 콘텐츠를 검토해 달라고 하게 되면 그들도 제대로 보지 않고 승인하는 문제가 생겨날 수 있습니다. 콘텐츠에 대해 면밀한 분석과 이해 없이 검토 요청을 승인하는 겁니다. "how we write/review code in big tech companies"라는 제목의 유튜브 영상에서는 이런 문제를 잘 보여줍니다. 동영상 속에서 엔지니어는 일부 코드를 완전히 이해하지 못한 상태로 수정한 후 문제가 있다면 검토자가 체크해 주리라 기대하며 코드를 제출합니다. 하지만 검토 엔지니어도 코드를 완전히 이해하지 못하고 "LGTM!"이라는 코멘트만 남기고 승인 처리합니다. 이 시나리오는 우스꽝스러워 보이지만 여기에 진실이 담겨 있습니다. 많은 사람들이 수정 사항을 제대로 이해하지 못하고 이게 맞게 수정된 것인지 알 수 있는 지식이 없는 상태에서 "LGTM!"을 남긴다는 겁니다. 그들은 그저 풀 리퀘스트나 변경 목록을 대기열에서 제거하고 싶을 뿐이며 작업자가 제대로 처리했다고 가정합니다.
https://www.youtube.com/watch?v=rR4n-0KYeKQ
테크니컬 라이터가 그럴듯하게 보이지만 실제로는 그렇지 않은 AI가 작성한 콘텐츠를 복사해 사용한다고 가정해 보겠습니다. 검토자는 이 콘텐츠를 AI가 작성했다는 사실을 깨닫지 못한 채 콘텐츠를 신뢰하고 넘어갑니다(AI 도구는 그럴듯하게 들리는 글을 쓰는 데 능숙합니다). 해당 콘텐츠를 AI 도구를 사용해 작성했다는 사실을 테크니컬 라이터가 밝히지 않는 한 검토자는 특별한 주의를 기울이지 않을 가능성이 높습니다. 적어도 사람이 글을 쓸 때는 테크니컬 라이터가 전혀 다른 이야기를 작성할 가능성이 훨씬 적고 필요한 경우 엔지니어에게 물어볼 겁니다.
좀 더 많은 콘텍스트 수집하기
일반적인 버그 처리 시나리오에서 언급한 것처럼 정보와 콘텍스트가 부족해 버그를 이해하고 조치를 취하기 어렵다는 것이 가장 큰 문제입니다. 콘텍스트, 정보의 부족을 개선하기 위해 제가 취한 한 가지 조치는 버그를 제출하는 사람들이 필요한 정보를 자세히 제공하도록 하는 것입니다. 다음은 요구사항 등록 시 요청자로부터 가능한 모든 정보를 짜내려는 템플릿입니다. 민감한 정보는 삭제했지만 자세히 읽어보면 어떤 의도인지 알 수 있을 겁니다.
아래의 모든 질문에 대한 답변을 작성해 주세요.
참고: 가능한 많은 정보를 제공해 주시면 자세한 내용을 확인하기 위해 후속 미팅을 진행하지 않아도 됩니다. 문서 업데이트를 위한 콘텍스트가 거의 없으므로(파트너 미팅, 엔지니어링 코딩 세션, 사후 분석 등) 문서 업데이트 시 제공해 주시는 정보가 매우 중요합니다.
1. 어떤 릴리스를 위한 것인가요? 릴리스 정보는 대기열에 있는 다른 버그에 대해 해당 작업의 우선순위를 더 잘 정할 수 있습니다. 업데이트가 릴리스와 관련이 없는 경우에는 "릴리스 없음"을 표시해 주세요.
2. 업데이트 우선순위는 무엇인가요? 여러분이 판단하기에 P0, P1, P2, P3 중 어떤 것에 해당하나요?(P0 요청인 경우에는 그 사유를 자세하게 설명해 주세요).
3. 어떤 API를 업데이트하나요?
4. API 운영 위원회와 변경 사항을 검토했나요? 그렇다면 관련 버그와 변경 요청 문서를 협의회에 제출하세요. 제품 출시 항목이 이는 경우 해당 링크도 포함하세요.
5. 업데이트를 설명하는 다른 소스 자료(예를 들어 기능 문서, 엔지니어링 문서, 제품 리뷰 문서)가 있나요? 문서에 제안된 여러 해결책 중 어떤 해결책으로 결정됐는지 기록해 주세요.
6. 문서 작업 요청과 관련된 엔지니어링 버그가 있나요? 예를 들어 일부 코드가 다른 변경 요청으로 처리되고 있는 엔지니어링 버그가 있나요? 더 자세한 정보를 제공하는 다른 버그가 있나요? 문서 변경 시 참조할 수 있는 모든 관련 버그를 나열하세요.
7. 관련 버그에 코드 변경과 관련된 변경 목록이 없는 경우에는 변경 목록을 기재해 주세요. 문서 업데이트 시 필요한 경우 코드를 비교해 확인해 볼 수 있습니다.
8. 이메일 스레드나 회의록을 PDF로 만들어 첨부할 수 있나요? 더 많은 콘텍스트를 제공하는 자료가 있나요?
9. 업데이트 시 변경되는 proto, class, 소스 파일은 어떤 것인가요(문서는 proto, 공개 class 파일의 주석을 바탕으로 생성되므로 대상 파일을 식별하면 주석을 변경하는 데 도움이 됩니다).
10. 업데이트에 대한 릴리스 노트를 작성하세요. field, class 이름을 구체적으로 명시하세요. 사용자가 업데이트를 이해하는 데 필요한 만큼 상세하게 설명하세요.
11. 기능 릴리스 상태를 표시합니다.
12. field, method 등이 다른 API에도 표시되나요? 어떤 것들인가요?(서로 다른 API에서 같은 field에 대한 중복되고 상충되는 설명을 체크하고자 합니다).
13. 이번 변경 사항이 문서의 코드 샘플에 영향을 미치나요?
14. 업데이트된 문서를 제출하기 전에 누가 이 콘텐츠를 검토하고 승인해야 하나요? 관련 이해관계자가 있다면 기재해 주세요.
궁금한 점이 있다면 이메일이나 채팅을 통해 문의해 주세요.
버그를 제출하는 일은 시간이 많이 걸리고 요청자에게 다소 고통스러울 수 있지만 테크니컬 라이터에게는 매우 보람 있는 일입니다. 누군가 업데이트 요청 시 이 모든 정보가 수집되어 있다고 상상해 보세요. 실제로 버그를 해결할 수 있을지도 모릅니다!
이렇게 수집된 콘텍스트에서 정보를 하나의 구글 문서에 복사하고 AI가 잘못 이해할 수 있는 부분을 모두 제거한 다음 콘텍스트로서 문서를 제공할 수 있습니다. 제거할 부분은 다음과 같습니다.
- 이메일 스레드에서 잘못된 답변
- 구현되지 않은 대체 해결책
- 아직 관련성이 없는 향후 계획
- 필요한 업데이트와 관련이 없는 불필요한 설명
결론
AI를 사용하는 것은 여러 가지 잠재적인 문제가 있지만, 문서 버그 수정은 AI 도구를 활용하기에 가장 적합한 분야 중 하나입니다. 앞으로 다양한 기법을 살펴보고 어떤 것이 효과가 있고 어떤 것은 효과가 없는지 살펴보고 제 경험을 공유하겠습니다.
