본문으로 건너뛰기

커뮤니티

팁 운영진 번역

OpenAI Cookbook: 좋은 문서를 만드는 방법

리퀘오 운영팀

이 글은 OpenAI Cookbook에 실린 OpenAI의 글을 한국어로 옮긴 것이다. 문서를 직접 쓰는 개발자와 기술 문서를 다듬는 사람에게, 읽는 사람의 시간을 아껴 주는 문서 작성 원칙을 정리해 준다. 문서는 쓸모 있는 정보를 다른 사람의 머릿속에 넣는 일이다.

1. 훑어보기 쉬운 문서로 만들기

독자는 문서를 위에서 아래로 차례로 읽지 않는다. 이 문단, 저 문단을 건너뛰며 자기 문제를 풀어 줄 부분을 찾는다. 탐색 시간을 줄이고 성공 확률을 높이려면 문서를 훑어보기 쉽게 만들어야 한다.

- 내용을 제목으로 나눠라. 절 제목은 표지판 역할을 해서, 독자가 여기에 집중할지 넘어갈지 판단하게 해 준다.
- 제목은 추상적인 명사보다 정보를 담은 문장으로 써라. '결과'라는 제목은 독자가 본문을 읽어야 결과가 무엇인지 알 수 있다. '스트리밍으로 첫 토큰까지 걸리는 시간이 50% 줄었다'라면 한 번 더 들어가지 않아도 바로 정보를 얻는다.
- 목차를 넣어라. 목차는 해시 맵이 연결 리스트보다 조회가 빠른 것처럼 정보를 빨리 찾게 해 준다. 목차는 문서의 성격을 미리 알려 줘서 읽을 가치가 있는지 판단하는 데도 도움이 된다.
- 문단은 짧게 유지하라. 꼭 전해야 할 핵심은 한 문장짜리 문단으로 따로 빼면 놓칠 확률이 줄어든다. 긴 문단은 정보를 묻어 버린다.
- 문단과 절은 그 자체로 이해되는 짧은 주제 문장으로 시작하라. 훑어보는 독자는 첫 단어, 첫 줄, 첫 문장에 유난히 눈길을 준다. '이를 바탕으로 이제 더 빠른 방법을 이야기해 보자' 같은 문장은 앞 문단을 읽지 않은 사람에게는 의미가 없다. '벡터 데이터베이스는 임베딩 검색을 빠르게 한다'처럼 앞 내용 없이도 통하는 문장으로 써라.
- 주제어를 주제 문장 앞에 두라. 한두 단어만 읽고도 문단이 무엇에 관한 것인지 알 수 있을 때 훑어보기가 가장 효율적이다. '임베딩 검색은 벡터 데이터베이스로 빨라질 수 있다'보다 '벡터 데이터베이스는 임베딩 검색을 빠르게 한다'가 낫다.
- 핵심 결론을 앞에 배치하라. 가장 중요한 정보는 문서와 절의 맨 앞에 둔다. 소크라테스식으로 조금씩 끌어올리지 말고, 결과보다 절차를 먼저 소개하지도 마라.
- 목록과 표를 활용하라. 글머리 기호 목록과 표는 문서를 훑어보기 쉽게 만든다. 자주 써라.
- 중요한 문장은 굵게 표시하라. 독자가 찾기 쉽도록 굵게 표시하는 것을 두려워하지 마라.

2. 잘 쓰기

잘못 쓴 글은 읽는 데 부담이 된다. 문장을 단순하게 유지하고, 긴 문장은 둘로 나눠라. 부사와 불필요한 단어·구절은 덜어 내라. 해당된다면 명령형을 써라. 글쓰기 책이 하라는 대로 하면 된다.

문장은 한 가지 뜻으로만 읽히게 써라. 첫 낱말이 명사인지 동사인지 바로 알 수 없는 문장은 독자가 끝까지 읽으며 뜻을 다시 맞춰야 해서 힘이 든다. 조금 길어지더라도 '절 제목은 문장으로 써라'처럼 한 번에 뜻이 잡히는 문장이 낫다. '자전거 정리 훈련 안내'처럼 명사만 이어 붙인 구절도 해석에 힘이 더 든다.

독자가 낱말 하나를 오래 붙들고 있어야 하는 문장은 피하라. 원문은 영어 문장 구조를 예로 들어, 무엇을 위한 내용인지 문장 끝에 가서야 밝혀지는 문장이 기억에 더 큰 부담을 준다고 설명한다. 예를 들어 재료 목록을 길게 늘어놓은 뒤 마지막에 '팬케이크를 만들 때 필요하다'고 밝히기보다, '팬케이크를 만들려면 밀가루, 달걀, 우유, 버터, 소금 약간이 필요하다'처럼 목적을 먼저 밝히는 편이 읽기 쉽다. 이런 문장이 보이면 순서를 바꿔 쓸 수 있는지 살펴라.

지시 대명사, 특히 앞 문장을 가리키는 '이것' 같은 말은 피하라. '앞에서 다룬 주제에 이어 이제 함수 호출을 이야기하자'보다 '메시지 형식에 이어 이제 함수 호출을 이야기하자'가 이해하기 쉽다. 독자가 앞 주제를 떠올리지 않아도 되기 때문이다. 아예 '이제 함수 호출을 이야기하자'처럼 지시 대명사를 없앨 수 있는지도 살펴라.

일관성을 지켜라. 사람의 뇌는 패턴을 잘 찾아낸다. 일관성이 없으면 독자가 거슬려하거나 집중을 잃는다. 제목 표기법을 하나로 통일하고, 쉼표 규칙도 통일하라. Cookbook 노트북 이름이 밑줄과 문장형 표기라면 그것으로 통일하라. 독자가 '어, 이상한데' 하게 만들지 말고 내용에 집중하게 하라.

독자가 무엇을 생각하는지, 무엇을 해야 하는지 단정하지 마라. '이제 함수를 어떻게 호출하는지 알고 싶을 것이다'나 '다음으로 함수 호출을 배워야 한다'는 독자의 상태를 추정해서 불쾌하게 하거나 신뢰를 떨어뜨릴 수 있다. '함수를 호출하려면 …'처럼 독자의 상태를 가정하지 않는 표현을 써라.

3. 폭넓게 도움이 되게 쓰기

문서를 찾는 사람의 지식 수준, 언어 능력, 인내심은 제각각이다. 숙련된 개발자를 대상으로 하더라도 모두에게 도움이 되는 문서를 쓰려고 해야 한다.

- 단순하게 써라. 필요하다고 생각하는 것보다 더 단순하게 설명하라. 영어가 모국어가 아닌 독자도 많고, 기술 용어에 혼란을 겪어 영어 문장을 해석할 여유가 거의 없는 독자도 많다. 다만 지나치게 단순화하지는 마라.
- 약어를 피하라. 풀어서 써라. 숙련자에게 드는 비용은 적고 초보자에게 돌아가는 이득은 크다. IF 대신 '지시 따르기', RAG 대신 '검색 증강 생성'처럼 풀어 써라(글쓴이는 '검색 후 질문하는 절차'라는 말을 더 좋아한다).
- 예상되는 문제에 해법을 제시하라. 독자의 95%가 파이썬 패키지 설치나 환경 변수 저장 방법을 안다 해도 미리 설명할 가치가 있다. 설명을 넣는 비용은 숙련자에게 적다. 그냥 훑고 지나가면 된다. 반대로 설명을 빼는 비용은 초보자에게 크다. 막히거나 아예 떠나 버릴 수 있다. 숙련된 JavaScript나 C++ 엔지니어도 파이썬에서는 초보일 수 있다는 점을 기억하라. 적게 설명하기보다 많이 설명하는 쪽으로 기울여라.
- 용어는 구체적이고 정확한 것을 선호하라. 전문 용어는 좋지 않다. 우리 자신이 아니라 분야에 새로 들어온 사람을 기준으로 문서를 최적화하라. '프롬프트' 대신 '입력', '컨텍스트 한도' 대신 '최대 토큰 한도'라고 써라. 후자가 더 자명하고, 기반 모델 시절에 생긴 전문 용어보다 나을 가능성이 크다.
- 코드 예제는 범용적이고 그대로 옮길 수 있게 유지하라. 의존성을 최소화하고, 추가 라이브러리를 설치하게 만들지 마라. 다른 페이지나 절을 오가며 참고하게 만들지도 마라. 예제는 단순하고 자기완결적으로 만들어라.
- 주제는 가치 순으로 우선순위를 정하라. 토큰 세는 법처럼 흔한 문제를 다루는 문서는 이모지 데이터베이스 최적화처럼 드문 문제를 다루는 문서보다 훨씬 가치가 크다. 그에 맞게 우선순위를 정하라.
- 나쁜 습관을 가르치지 마라. API 키를 코드에 저장하면 안 된다면, API 키를 코드에 저장하는 예제는 절대 공유하지 마라.
- 주제는 넓은 도입으로 시작하라. 좋은 추천 시스템을 프로그래밍하는 법을 설명한다면, 추천이 유튜브 영상부터 아마존 상품, 위키피디아에 이르기까지 웹 전반에 퍼져 있다는 점을 짧게 언급하며 시작하는 것을 고려하라. 좁은 주제를 넓은 도입으로 받쳐 주면 낯선 영역에 뛰어들기 전에 독자가 안심할 수 있다. 글이 잘 쓰였다면 이미 아는 독자도 즐길 수 있다.

4. 좋은 이유가 있다면 규칙을 깨도 된다

결국 가장 좋다고 생각하는 대로 하면 된다. 문서 작성은 공감의 연습이다. 독자의 입장이 되어, 그들에게 가장 도움이 될 일을 하라.

여러분은 문서를 쓰면서 어떤 원칙을 가장 자주 어기게 되는지, 혹은 어떤 팁이 특히 효과가 있었는지 댓글로 경험을 나눠 주세요.

---
출처: OpenAI Cookbook 「좋은 문서를 만드는 방법」 (OpenAI)
https://developers.openai.com/cookbook/articles/what_makes_documentation_good
저작권 고지(라이선스가 요구하는 원문 표기): Copyright (c) 2025 OpenAI · MIT 라이선스 https://github.com/openai/openai-cookbook/blob/main/LICENSE
변경 사항: 리퀘오 운영팀이 2026-11-10에 한국어로 번역하고 일부 축약·재구성했습니다. 원문 작성자가 이 번역을 보증하지 않습니다.

로그인하면 누를 수 있습니다. 로그인하면 저장하고 새 답글 알림을 받을 수 있습니다.

답글 0

아직 답글이 없습니다.