프로덕트 문서 작성 10가지 팁: 마크다운으로 전문가급 문서 만들기
사이드바 커스터마이징, 리소스 임베드, 레이아웃 구성, 인터랙티브 요소까지 프로덕트 문서를 전문가처럼 작성하는 10가지 핵심 팁을 알아봅니다.
Spacebar AI
2025년 12월 7일
6분
프로덕트 문서 작성 10가지 팁
훌륭한 문서는 제품의 일부입니다. 마크다운을 활용해 전문가급 프로덕트 문서를 작성하는 방법을 알아봅니다.
1. 사이드바 제목 커스터마이징
문서 제목과 사이드바 제목을 분리하여 사용성을 높입니다.
---
sidebar_title: "빠른 시작"
title: "5분 만에 시작하는 API 통합 가이드"
---
효과:
- 사이드바: 간결한 "빠른 시작"
- 문서 내부: 상세한 전체 제목
- 링크 미리보기 (Slack 등): 상세 제목 표시
2. 프로젝트 리소스 인용
API 엔드포인트, 스키마, 다른 문서를 직접 임베드합니다.
<!-- 엔드포인트 임베드 -->
{{endpoint:user-create}}
<!-- 스키마 임베드 -->
{{schema:UserResponse}}
<!-- 다른 문서 링크 -->
{{doc:authentication-guide}}
장점: 원본 스키마가 변경되면 임베드된 버전도 자동 업데이트됩니다.
3. 링크 동작 제어
링크 유형에 따라 적절한 동작을 설정합니다.
내부 링크 (현재 페이지)
[인증 가이드](apidog://link/pages/auth-guide)
외부 링크 (새 탭)
[GitHub 저장소](https://github.com/example){:target="_blank"}
앵커 링크 (페이지 내 이동)
[설치 섹션으로 이동](#installation)
4. 나란히 배치 레이아웃
비교나 병렬 정보를 위한 컬럼 레이아웃:
:::container
::column
### Before
기존 방식의 코드 예제
::
::column
### After
개선된 방식의 코드 예제
::
:::
활용 사례:
- 이전/이후 비교
- 다국어 예제
- 요청/응답 병렬 표시
5. 스텝 컴포넌트
복잡한 프로세스를 단계별로 안내:
:::steps
### 1단계: 설치
npm 또는 yarn으로 패키지를 설치합니다.
### 2단계: 설정
환경 변수를 구성합니다.
### 3단계: 실행
개발 서버를 시작합니다.
:::
6. 이미지 최적화
크기 조절
{width=600}
다크모드 대응
:::image-container{background="white"}
:::
캡션 추가
:::figure
*그림 1: 대시보드 메인 화면*
:::
7. 테이블 활용
구조화된 정보 표시:
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|:----:|------|
| api_key | string | ✅ | API 인증 키 |
| format | string | | 응답 형식 (json/xml) |
| limit | integer | | 결과 수 (기본: 10) |
컬럼 너비 조절
<table>
<colgroup>
<col style="width: 20%">
<col style="width: 15%">
<col style="width: 10%">
<col style="width: 55%">
</colgroup>
...
</table>
8. 아코디언 블록
FAQ나 선택적 정보를 접을 수 있게:
:::details{summary="자주 묻는 질문"}
### Q: API 키는 어디서 발급받나요?
설정 > API 키 메뉴에서 발급받을 수 있습니다.
### Q: Rate limit은 얼마인가요?
무료 플랜: 100 요청/분
프로 플랜: 1000 요청/분
:::
9. 알림 및 하이라이트
중요 정보 강조:
팁
:::tip
성능 향상을 위해 캐싱을 활성화하세요.
:::
경고
:::warning
이 작업은 되돌릴 수 없습니다.
:::
위험
:::danger
프로덕션에서는 절대 사용하지 마세요.
:::
정보
:::info
이 기능은 v2.0부터 사용 가능합니다.
:::
10. 인터랙티브 요소
툴팁
API 키는 {{tooltip:Bearer 토큰|HTTP 헤더에 포함되는 인증 토큰입니다}}으로 전달됩니다.
클립보드 복사
:::copy
npm install @example/sdk
:::
조합 활용
설치 명령어: {{copy:npm install @example/sdk}}
보너스: 문서 구조화 베스트 프랙티스
📁 Docs
├─ 📄 시작하기
│ ├─ 빠른 시작
│ ├─ 설치 가이드
│ └─ 첫 번째 API 호출
├─ 📄 핵심 개념
│ ├─ 인증
│ ├─ 에러 처리
│ └─ Rate Limiting
├─ 📄 API 레퍼런스
│ ├─ Users
│ ├─ Products
│ └─ Orders
├─ 📄 가이드
│ ├─ 웹훅 설정
│ └─ SDK 사용법
└─ 📄 FAQ
결론
좋은 문서는 커뮤니케이션 비용을 줄이고 제품 채택률을 높입니다. 이 10가지 팁을 활용하여 사용자가 쉽게 이해하고 따라할 수 있는 문서를 작성하세요.