인간을 위한 글쓰기만으로는 충분하지 않다. AI를 위한 글쓰기가 이제 업무의 일부가 되었다.

Source: Dev.to

Introduction

제가 근무하는 회사가 문서 플랫폼에 AI 어시스턴트를 통합했을 때, 저는 초기 테스트 팀 중 하나에 선정되었습니다. 목표는 기존 문서를 진실의 원천으로 활용하여 AI가 실제 사용자 질문에 얼마나 잘 답변할 수 있는지를 확인하는 것이었습니다.

제가 예상하지 못했던 것은 이 실험이 기술 문서 작성에 대한 제 사고 방식을 얼마나 크게 바꿔놓을지였습니다.

이것은 단순히 AI 정확도에 관한 문제가 아니었습니다. 문서 자체가 대규모 언어 모델(LLM)에 의해 소비될 때 어떻게 동작하는가에 관한 문제였습니다.

LLM은 결정론적이지 않으며, 이는 버그가 아니다

AI 어시스턴트를 테스트하면서 처음 눈에 띈 점 중 하나는 같은 질문을 여러 번 했을 때, 같은 문서와 같은 벡터 데이터베이스 기반 검색, 그리고 동일한 기본 모델을 사용했음에도 불구하고 답변이 달라지는 경우가 있다는 것이었습니다.

처음에는 이것이 신뢰성 문제처럼 보였습니다. 실제로는 중요한 사실을 드러낸 것이었습니다: LLM은 확률적이며 결정론적이지 않다는 점입니다. 답변은 질의 문구, 검색된 컨텍스트, 토큰 확률, 그리고 의미 유사도 검색에 따라 생성됩니다. 검색된 내용이 모호하거나 얇거나 범위가 명확하지 않을 경우, 답변이 달라질 수 있습니다.

최소주의적 글쓰기는 인간에게는 효과적이지만 AI에게는 항상 그렇지는 않다

우리 문서는 깔끔하고 최소주의적인 글쓰기 스타일을 따랐습니다. 짧은 페이지, 적은 단어 수, 그리고 최소한의 설명으로 인간 독자에게 최적화되었습니다.

하지만 AI는 이를 어려워했습니다.

왜? 최소주의 문서는 종종 명시적인 주제 의도, 명확한 제품 경계, 모호성을 해소하는 컨텍스트, 그리고 페이지가 실제로 무엇에 관한 것인지 설명하는 짧은 요약이 부족하기 때문입니다. 인간은 경험을 통해 의미를 추론합니다. LLM은 그렇지 못합니다.

Common terminology confuses AI more than you think

A recurring issue came from shared terminology across products. Terms like virtual server, instance, node, and environment existed across multiple products in our ecosystem.

When users asked, “How do I create a virtual server?” the AI sometimes pulled steps from the wrong product, simply because multiple pages used the same wording and the pages didn’t clearly state which product they belonged to.

The AI wasn’t hallucinating. It was retrieving valid but irrelevant content.

해결책은 놀라울 정도로 간단했습니다: 더 많은 컨텍스트 추가

우리는 선택된 페이지에서 작은 실험을 진행했습니다. 각 페이지 시작 부분에 간결한 설명을 추가하고, 모든 주제와 하위 주제에 짧은 요약을 도입했으며, 단계별 설명을 강화해 명확성을 높이고, 불필요한 교차 참조를 줄였습니다.

결과: AI 답변이 더 정확해지고, 검색 관련성이 향상되었으며, 혼합 제품 응답이 감소하고, 사용자는 AI가 생성한 답변에 대한 신뢰도가 높아졌습니다. 개선 효과를 확인한 후, 우리는 이 접근 방식을 문서 전체에 확대 적용했습니다.

교차 참조는 AI 검색에 해로울 수 있습니다

너무 많은 교차 참조는 AI의 혼란을 증가시킵니다. 페이지가 다른 주제를 많이 참조할 때, AI는 때때로 메인 주제 대신 연결된 페이지의 답변을 생성하고, 부분적인 단계들을 섞어 버리며, 맥락을 잃었습니다.

우리는 필요할 때만 교차 참조를 사용하고, 주요 워크플로를 자체적으로 유지하며, 순환 링크를 피하는 방식으로 접근 방식을 조정했습니다. 이를 통해 검색 잡음이 감소하고 답변 일관성이 향상되었습니다.

이것이 기술 작가에게 의미하는 바

기술 작가들은 이제 더 이상 인간만을 위해 글을 쓰는 것이 아니다. 우리는 AI 시스템을 위한 지식을 설계하고, 기계 검색을 위한 모호성을 줄이며, 신뢰할 수 있는 AI 답변이 어떻게 가능한지를 정의하고 있다.

좋은 AI 답변은 더 나은 모델에서 시작되는 것이 아니다. 더 나은 문서에서 시작된다.

Practical writing tips for AI‑ready documentation

• 모든 주제에 짧고 명확한 설명을 추가하세요.
• 페이지 초반에 제품 범위를 명확히 명시하세요.
• 독자(또는 AI)가 상황을 알고 있다고 가정하지 마세요.
• 제품 전반에 걸쳐 사용되는 일반 용어를 구분하세요.
• 최소주의 흐름과 의미 있는 맥락을 균형 있게 유지하세요.
• 불필요한 교차 참조를 줄이세요.
• 주제 소개를 “검색 앵커”로 작성하세요.

Final thought

LLM은 기술 작가를 대체하지 않는다. 그것은 우리가 만드는 문서의 품질을 향상시킨다.

문서가 명확하고 범위가 정해져 있으며 의도적일 때 AI는 강력한 조수가 된다. 그렇지 않을 경우 AI는 이미 존재하는 혼란을 그대로 반영할 뿐이다.