문서화(Documentation)는 개발자가 처음으로 경험하는 제품인 경우가 많습니다.

개발자가 여러분의 아키텍처(Architecture), 엔지니어링 문화(Engineering culture), 또는 코드 품질(Code quality)을 보기 전에, 먼저 여러분의 문서와 상호작용합니다.

만약 그 경험이 혼란스럽거나, 불완전하거나, 좌절감을 준다면, 많은 개발자는 첫 번째 성공적인 API 요청에 도달하지 못할 것입니다.

지난 몇 주 동안, 저는 무엇이 온보딩(Onboarding)을 원활하게 만드는지, 그리고 팀들이 의도치 않게 어디에서 마찰(Friction)을 만드는지 이해하기 위해 AI 스타트업들의 문서를 검토해 왔습니다.

모든 회사가 다르지만, 동일한 패턴이 계속해서 나타났습니다.

1. 퀵스타트(Quickstarts)가 너무 많은 것을 가정함

많은 퀵스타트(Quickstarts)가 사전 요구 사항(Prerequisites)을 설명하지 않고 바로 코드로 뛰어듭니다.

개발자들은 다음과 같은 사항을 알고 있다고 가정됩니다:

• API 키를 어디에서 가져오는지
• 어떤 SDK를 설치해야 하는지
• 필요한 환경 변수(Environment variables)
• 인증(Authentication) 단계

퀵스타트(Quickstart)는 사용자가 가능한 한 추측을 최소화하면서 제로(Zero) 상태에서 성공적인 요청까지 도달할 수 있도록 도와야 합니다.

2. 에러 메시지(Error messages)가 문서화되어 있지 않음

개발자들은 모든 것이 잘 돌아갈 때 문서가 어떻게 작동하는지로 문서를 판단하지 않습니다.

그들은 무언가 잘못되었을 때 문서가 얼마나 빨리 복구(Recover)를 도와주는지로 문서를 판단합니다.

에러 코드(Error codes)만 나열하는 대신, 다음을 설명하세요:

• 에러가 발생하는 이유
• 일반적인 원인
• 해결 방법
• 다음에 시도할 사항

좋은 트러블슈팅(Troubleshooting) 문서는 신뢰를 구축합니다.

3. 예시(Examples)가 불완전함

너무 많은 예시가 중요한 세부 사항을 누락합니다.

개발자들이 다음과 같은 사항을 추론하게 해서는 안 됩니다:

• 인증 헤더(Authentication headers)
• 환경 변수(Environment variables)
• 요청 페이로드(Request payloads)
• 예상 응답(Expected responses)

예시는 복사(Copy), 붙여넣기(Paste), 실행(Run), 그리고 이해(Understand)할 수 있어야 합니다.

4. 명확한 학습 경로(Learning path)가 없음

문서는 종종 안내된 여정(Guided journey)이라기보다 페이지들의 집합처럼 느껴집니다.

더 나은 구조는 다음과 같을 수 있습니다:

1. 퀵스타트(Quickstart)
2. 핵심 개념(Core Concepts)
3. 튜토리얼(Tutorials)
4. API 레퍼런스(API Reference)
5. 고급 가이드(Advanced Guides)
6. 트러블슈팅(Troubleshooting)

개발자들이 다음에 무엇을 읽어야 할지 항상 알게 되면, 더 빠르게 진전을 이룰 수 있습니다.

5. 문서가 AI 지원 개발(AI-assisted development)을 위해 작성되지 않음

오늘날 개발자들은 점점 더 AI 코딩 어시스턴트 (AI coding assistants)에 의존하고 있습니다.

이는 문서 또한 AI 도구가 해석하기 쉬워야 함을 의미합니다.

여기에는 다음 사항들이 포함됩니다:

• 일관된 헤딩 (headings)
• 명확한 용어 (terminology)
• 구조화된 예시 (structured examples)
• 명시적인 파라미터 설명 (explicit parameter descriptions)
• 예측 가능한 페이지 구성 (predictable page organization)

잘 구조화된 문서는 인간과 AI 시스템 모두가 정확한 정보를 검색하는 데 도움을 줍니다.

6. "다음 단계 (next steps)"의 부재

성공적인 API 호출이 여정의 끝이 되어서는 안 됩니다.

개발자들이 의미 있는 진전을 이룰 수 있도록 안내하세요:

• 챗봇 구축하기
• 파일 업로드하기
• 사용자 인증하기
• 응답 스트리밍하기
• 고급 기능 탐색하기

모멘텀 (momentum)이 중요합니다.

7. 문서화를 사후 고려 사항으로 취급함

가장 강력한 엔지니어링 팀은 문서화를 제품의 일부로 취급합니다. 코드가 배포된 후에 작성하는 무언가가 아닙니다.

문서화는 다음을 개선합니다:

• 개발자 경험 (developer experience)
• 제품 채택 (product adoption)
• 지원 효율성 (support efficiency)
• 고객 성공 (customer success)
• 개발자 신뢰 (developer trust)

문서화는 단순한 지원 리소스가 아닙니다.

그것은 성장 자산입니다.

나의 도전 (My Challenge)

저는 AI 스타트업의 문서를 검토하고 실질적인 개선 사항을 공유하는 공개 챌린지를 시작하려 합니다.

각 검토에는 다음이 포함됩니다:

• 팀이 잘한 점 한 가지
• 개선 기회 한 가지
• 다시 작성된 예시 또는 제안

목표는 비판하는 것이 아닙니다.

배우고, 기여하며, 더 나은 개발자 경험을 만드는 데 도움을 주는 것입니다.

만약 공개 문서를 갖춘 AI 제품을 만들고 계신다면, 제가 검토해 드리고 싶습니다.

저는 항상 사려 깊은 문서화의 사례를 찾고 있으며, 좋은 문서를 더욱 훌륭하게 만들 기회를 찾고 있습니다.

읽어주셔서 감사합니다!