AI, Confluence Docs, 그리고 READMEs: AI가 작성한 문서가 읽히지 않는 이유
Source: Dev.to
AI가 문서화에 가져다 주는 약속
분명히 말씀드리자면, 저는 AI 사용을 반대하는 것이 아닙니다. 사실 저는 AI를 많이 사용한 적이 있습니다. 그것은 가볍고, 수고롭지 않으며, 놀라울 정도로 빠랐습니다. 몇 시간 걸렸을 Confluence 페이지가 몇 분 안에 나타났습니다. 생산적인 느낌이었고, 한동안은 그랬을지도 모릅니다.
AI는 무에서 구조를 만들고, 일관된 템플릿을 생성하며, 코드를 텍스트로 변환하고, 명백한 부분을 채워 빈 페이지를 바라보지 않게 하는 데 진정으로 유용합니다. 시간에 쫓기는 팀에게는 그 속도가 설득하기 어렵습니다.
충격이 닥친 순간
문제는 즉시 나타나지 않았다. 한 달 정도 지나서 그 AI‑생성 문서 중 하나를 다시 살펴보았을 때 그 요점을 이해하지 못하면서 명확해졌다. 글은 내 것이었고, 페이지는 완전했지만 의미가 잡히지 않았다.
나는 단락을 다시 읽고, 위아래로 스크롤하며 시스템이 실제로 무엇을 했는지, 왜 그렇게 했는지를 재구성하려 애썼다. 그때 깨달았다: 문서는 작성되었지만, 명확히 표현되지 않은 것이다.
문서화의 진정한 목적
문서화의 주요 목적은 페이지에 텍스트를 넣는 것이 아닙니다. 아이디어를 쉽게 이해하고, 쉽게 기억할 수 있으며, 몇 달—혹은 1년이 지나도 여전히 명확하게 전달하는 것입니다. 좋은 문서는 시간이 지나도 살아남습니다. 1년 후에 다시 찾아가 몇 섹션을 훑어보면 이 것이 무엇을 하는지, 왜 존재하는지, 그리고 어떤 점을 주의해야 하는지를 즉시 떠올릴 수 있어야 합니다.
AI가 생성한 문서는 종종 이 테스트에 실패합니다.
왜와 어떻게 물어도 아직 부족하다
AI 문서에 대한 비판에 흔히 하는 반응은 “프롬프트를 더 잘 작성하고 왜와 어떻게를 물어보라”는 것이다. 나도 그렇게 해봤다. 어느 정도 도움이 되긴 하지만, 결과물은 여전히 지나치게 장황하고 추상적이며, 맞는 듯 보이지만 기억에 남지 않는 개념들로 가득 차 있다.
그 결과는 겉보기엔 철저해 보이지만 소화하기 어려운 문서가 된다. 독자의 주의를 끌기보다는 요구하게 만든다. 특히 Confluence와 같은 환경에서는 대부분의 독자가 그 문서를 끝까지 읽어내지 못한다.
장황함은 명확함과 다릅니다
AI는 종종 길이를 유용성과 동일시합니다. 짧은 설명, 명확한 사고 모델, “X 작업을 하지 않는 한 무시해도 됩니다”와 같은 간단한 안내 대신에, 긴 문단, 다르게 표현된 반복 아이디어, 그리고 거의 기억에 남지 않는 많은 단어들을 얻게 됩니다.
Confluence 페이지는 거의 정리되지 않기 때문에, 그 장황함은 수정되지 않고 조용히 읽히지 않은 채 그대로 남아 있습니다.
대화형 문서화의 힘
가장 효과적인 Confluence 페이지와 README는 팀원이 당신에게 설명해 주는 느낌입니다. 혼동을 예상하고, 기술 용어보다 먼저 쉬운 언어를 사용하며, 무엇이 중요한지와 중요하지 않은지를 알려줍니다.
AI 스타일:
This service abstracts the persistence layer for user‑related data.
Human 스타일:
This service exists so the rest of the app does not need to know how user data is stored. If we ever change the database, this is the only place we should need to update.
같은 의미. 경험은 매우 다릅니다.
인간이 아직도 AI보다 더 잘하는 것
- 인간은 트레이드오프와 현실을 포착하고 “이것은 이상적이지 않지만 당시 가장 안전한 옵션이었다”, “우리는 여기서 속도를 최적화했다”, “이것을 변경할 때 조심하세요. 이전에 문제가 있었거든요”와 같은 메모를 남깁니다. AI는 이러한 경계를 매끄럽게 처리하려는 경향이 있지만, 인간은 이를 문서화하고 바로 그곳에 진정한 가치가 있습니다.
- 인간은 코드에 존재하지 않는 맥락을 추가합니다: 과거 사건, 조직적 제약, 압박 속에서 내린 결정 등. 이러한 맥락이 없으면 문서는 기술적으로는 정확하지만 실제로는 도움이 되지 않을 수 있습니다.
- 인간은 “이 부분이 혼란스러워도 정상입니다. 아마 건드릴 필요는 없을 겁니다” 혹은 “막히면 이 팀에 문의하세요”와 같은 안심 메모로 불안을 줄여줍니다. AI는 이런 식으로 자연스럽게 제공하기 어렵습니다.
AI를 어떻게 사용해야 할까
이는 AI에 대한 경고가 아니라 검토되지 않은 AI에 대한 경고입니다. AI는 훌륭한 출발점이지만 최종 저자로서는 적합하지 않습니다.
보다 건전한 접근 방식은 AI가 초안을 생성하도록 하고, 이후 인간이 검토하도록 하는 것입니다:
- 불필요한 장황함 제거
- 불필요한 전문 용어 삭제
- 맥락과 의견 추가
- 섹션을 대화형으로 다시 작성
한 번 Confluence나 README에 올라가면, 조용히 오래도록 읽히지 않은 채 머무르는 경우가 많습니다. 바로 그래서 더욱 신경 써야 하는 것입니다.
최종 생각
AI는 문서를 빠르게 작성하도록 도와주었습니다. 또한 속도를 명확성으로 착각하기가 얼마나 쉬운지 알려주었습니다. 문서는 모든 것을 적는 것이 아니라, 핵심을 기억에 남을 방식으로 표현하는 것입니다.
AI는 존재하는 것을 설명할 수 있습니다. 인간은 중요한 것을 설명합니다.
AI를 사용하세요. 물론입니다. 다만 인간의 검토 없이 그 결과물을 영구적으로 남기지 마세요. 소비될 수 없는 문서는 사라지지 않고, 읽히지 않은 채 영원히 남아 있기 때문입니다.