좋은 기술문서는 왜 사람을 덜 헤매게 할까: 사용자 설명서와 API 문서의 차이

DevRel 준비 6주차 | 기술문서와 Developer Experience

---

지금까지 5주 동안 프로그래밍 언어, 웹과 앱, 프론트엔드와 백엔드, API, 데이터베이스와 클라우드를 차례로 살펴봤습니다. 오늘은 조금 다른 각도에서 이야기해보려 합니다. 기술 그 자체가 아니라, 기술을 설명하는 문서에 대한 이야기입니다.

이 주제는 제가 가장 오래, 가장 직접적으로 경험해온 영역입니다. 가전제품 매뉴얼을 개발하는 Technical Writer로 일하면서, 저는 수없이 많은 순간에 이런 질문을 스스로에게 던졌습니다. "이 문장은 읽는 사람에게 정말 도움이 될까? 아니면 그냥 정보를 나열한 것에 불과한가?"

오늘은 그 질문에 대한 제 나름의 답을 정리해보겠습니다.

---

같은 내용, 다른 경험: 문서가 만드는 차이

먼저 간단한 실험을 해보겠습니다. 아래 두 문장을 읽어보세요. 둘 다 같은 기능을 설명하고 있습니다.

버전 A:

"본 제품의 무선 네트워크 연결 기능을 활성화하기 위해서는 설정 메뉴 내 네트워크 항목에서 해당 옵션을 선택하여 활성화 상태로 전환하십시오."

버전 B:

"Wi-Fi를 켜려면: 설정 → 네트워크 → Wi-Fi를 탭하고, 스위치를 오른쪽으로 밀어주세요."

어느 쪽이 더 빠르게 이해되셨나요? 버전 B라고 느끼셨다면, 그 이유를 한번 분석해볼게요.

버전 A는 틀린 정보가 없습니다. 하지만 읽는 사람이 머릿속에서 한 번 더 번역해야 합니다. "활성화 상태로 전환"이 스위치를 켜는 것이라는 걸 알아야 하고, 어떤 순서로 메뉴를 탐색해야 하는지 스스로 조합해야 합니다. 버전 B는 그 번역 과정을 문서가 대신 해줍니다. 읽는 사람이 생각 없이 따라갈 수 있도록 길을 미리 닦아둔 것이죠.

좋은 문서는 독자의 인지 부하를 줄여줍니다. 이것이 제가 Technical Writing을 통해 배운 가장 핵심적인 원칙입니다.

---

사용자 설명서와 API 문서: 독자가 다르면 문서도 달라야 한다

기술 문서에는 여러 종류가 있지만, 오늘은 제가 가장 많이 비교하게 되는 두 가지를 이야기해보겠습니다. 사용자 설명서와 API 문서입니다.

사용자 설명서: 결과 중심, 행동 중심

제가 작성하는 가전제품 매뉴얼이 대표적인 사용자 설명서입니다. 독자는 제품을 처음 사용하는 일반 소비자입니다. 이들에게 중요한 것은 "이 버튼이 어떤 회로와 연결되어 있는가"가 아니라, "이 버튼을 누르면 어떤 일이 일어나는가"입니다.

사용자 설명서의 특징:

• 결과 중심: "세탁이 완료되면 알림음이 울립니다"처럼 사용자가 경험하게 될 결과를 중심으로 설명
• 행동 중심: "버튼을 누르세요", "레버를 돌리세요"처럼 구체적인 행동 지시
• 오류 상황 대비: "만약 화면에 E3이 표시된다면"처럼 사용자가 겪을 수 있는 문제 상황과 해결 방법 포함
• 기술 용어 최소화: 독자가 기술 배경지식 없이도 이해할 수 있어야 함

API 문서: 구조 중심, 명세 중심

API 문서의 독자는 다릅니다. 개발자입니다. 개발자는 API를 사용해서 자신의 서비스를 만들거나 기능을 연결해야 합니다. 이들에게는 "이 API가 어떤 요청을 받고, 어떤 응답을 돌려주는가"라는 정확한 명세가 필요합니다.

API 문서의 특징:

• 요청과 응답 명세: 어떤 형식으로 데이터를 보내야 하는지, 어떤 형식으로 응답이 오는지 정확하게 정의
• 예시 코드: 실제로 어떻게 사용하는지 코드 샘플로 보여줌
• 에러 코드 목록: 어떤 상황에서 어떤 에러가 발생하는지 명확하게 안내
• 버전 관리: API가 업데이트되면 이전 버전과 무엇이 달라졌는지 명시

---

문서가 개발자 경험(DX)을 바꾸는 방법

여기서 DX(Developer Experience), 즉 개발자 경험이라는 개념이 등장합니다. DX는 개발자가 어떤 도구, API, 플랫폼을 사용할 때 얼마나 쉽고 빠르게 원하는 것을 이룰 수 있는지를 나타내는 개념입니다.

제가 이 개념을 처음 접했을 때, 사용자 설명서를 작성하면서 늘 고민했던 것과 본질적으로 같다는 것을 느꼈습니다. 독자가 일반 소비자냐 개발자냐의 차이가 있을 뿐, "이 문서를 읽는 사람이 원하는 것을 빠르고 정확하게 이룰 수 있는가"라는 질문은 동일합니다.

나쁜 DX의 대표적인 사례들:

• 에러 코드만 나열된 문서: "403: Forbidden"이라고만 쓰여 있고, 왜 이 에러가 발생했는지, 어떻게 해결해야 하는지 알 수 없는 경우
• 실행 가능한 예시 코드가 없는 문서: 설명만 있고 실제 코드 예시가 없어서 개발자가 스스로 조합해서 시도해보고 실패를 반복해야 하는 경우
• 업데이트되지 않은 문서: API가 변경되었는데 문서가 이전 버전을 그대로 설명하고 있는 경우

좋은 DX의 핵심:

개발자가 문서를 읽고 나서 "이제 뭘 해야 하는지 알겠다"는 상태가 되어야 합니다.

---

실제 문서 작성에서 배운 것들

Technical Writer로 일하면서 제가 직접 경험한 몇 가지 원칙들을 나눠보겠습니다.

독자의 맥락을 먼저 이해해야 합니다

같은 기능을 설명하더라도, 처음 사용하는 사람과 기존에 사용해본 사람에게 필요한 정보는 다릅니다. 처음 사용하는 사람에게는 전체 흐름과 기본 설정이 중요하고, 기존 사용자에게는 바뀐 부분이 무엇인지가 중요합니다. 문서를 쓰기 전에 "이 문서를 읽는 사람은 어떤 상황에 있는가"를 먼저 생각해야 합니다.

정확성과 명확성은 둘 다 필요합니다

기술 문서에서 정확성은 당연한 기본입니다. 하지만 정확하기만 하고 명확하지 않은 문서는 읽는 사람을 헤매게 만듭니다. 앞서 버전 A의 예시처럼, 틀린 말이 없어도 이해하기 어려운 문서가 됩니다. 정확성과 명확성을 동시에 갖추는 것이 기술 문서의 핵심 과제입니다.

문서도 제품입니다

이 블로그 1주차에서 언급했던 것처럼, 문서는 단순한 설명서가 아니라 하나의 제품 경험입니다. 사용자가 제품을 처음 만나는 순간이 문서일 수 있고, 개발자가 API를 처음 접하는 순간이 문서일 수 있습니다. 그 첫 경험이 어떠냐가 그 사람이 계속 그 서비스를 사용할지 여부에 영향을 줍니다.

---

마무리하며

오늘 다룬 내용을 정리해보겠습니다.

• 좋은 문서는 독자의 인지 부하를 줄여주고, 읽는 사람이 원하는 것을 빠르게 이룰 수 있게 도와줍니다
• 사용자 설명서는 결과와 행동 중심으로, API 문서는 요청과 응답의 구조 중심으로 작성됩니다. 독자가 다르면 문서의 방향도 달라야 합니다
• DX(Developer Experience)는 개발자가 얼마나 쉽고 빠르게 원하는 것을 이룰 수 있는지에 관한 것이며, 좋은 문서는 DX를 직접적으로 개선합니다
• 문서는 설명서가 아니라 제품 경험의 일부입니다

다음 글에서는 요즘 가장 뜨거운 주제인 AI 툴 비교를 다뤄보겠습니다. ChatGPT, Claude, Gemini가 어떻게 다른지, 특히 문서 작성과 개념 학습, 리서치 관점에서 어떤 툴이 어떤 상황에 더 잘 맞는지 비전공 학습자의 현실적인 시각으로 정리해보겠습니다.

읽어주셔서 감사합니다.

---

TAG: #기술문서 #API문서 #사용자설명서 #DX #TechnicalWriting #DevRel준비 #DocsToDevRel #TechnicalWriter #DeveloperExperience #기초기술개념