vox.ai 문서 작성 규칙
이 문서는domains/voxai/docs/ 내 모든 MDX 페이지에 적용되는 작성 규칙이다.
새 페이지를 만들거나 기존 페이지를 수정할 때 반드시 따른다.
1. 브랜드 표기
- 서비스명은 vox.ai 로 표기한다 (대문자 X, 마침표 포함).
- “VOX”, “Vox”, “voxai” 등 다른 표기를 사용하지 않는다.
2. 시각 자료
페이지에 시각 자료를 적극 활용한다. 텍스트만으로 설명이 충분해도, 대시보드 화면이나 절차가 포함되면 반드시 시각 자료를 넣는다.| 유형 | 사용 시점 | 예시 |
|---|---|---|
| 이미지 | 대시보드 UI, 설정 화면, 결과 화면을 설명할 때 | 스크린샷, 다이어그램 |
| Mermaid | 절차, 흐름, 상태 전이를 설명할 때 | sequenceDiagram, flowchart, stateDiagram |
이미지 규칙
/images/디렉토리에 저장한다.- 파일명은
섹션-설명.png형식으로 작성한다 (예:deploy-batch-campaign-dialog.png). - 아직 이미지가 없으면
{/* screenshot: 설명 */}주석을 남겨 위치를 표시한다.
Mermaid 규칙
- 코드 블록으로 삽입한다:
```mermaid - 노드 텍스트는 한국어로 작성한다.
- 3단계 이상의 절차, 분기가 있는 흐름에 사용한다.
3. 언어 원칙
한영 병기를 하지 않는다. 한국어 또는 영어 중 하나만 선택한다.| 규칙 | 올바른 예 | 잘못된 예 |
|---|---|---|
| 한국어 용어가 있으면 한국어 사용 | 음성 에이전트 | 음성 에이전트(Voice Agent) |
| 고유명사는 원어 유지 | MCP, SDK, API, SIP, DTMF | 엠씨피, 에스디케이 |
| UI 레이블은 실제 화면 표기를 따름 | Settings → Connectors | 설정 → 커넥터 |
| 코드, CLI 명령은 영어 | mint dev | 민트 개발서버 실행 |
4. Mintlify 컴포넌트 활용
MINTLIFY.md와 Mintlify MCP를 참고하여 best practice를 따른다.
필수 frontmatter
컴포넌트 선택 기준
| 상황 | 컴포넌트 |
|---|---|
| 순서가 있는 절차 | <Steps> + <Step> |
| 택일 옵션 | <Tabs> + <Tab> |
| 부가 정보 접기 | <Accordion> |
| 페이지 카드 네비게이션 | <CardGroup> + <Card> |
| 주의/팁/정보 | <Warning>, <Tip>, <Note>, <Info> |
| 코드 다중 언어 | <CodeGroup> |
5. 페이지 간 링크
내부 링크 적극 활용
문서에서 다른 페이지에서 이미 설명한 개념이 등장하면, 해당 단어를 내부 링크로 연결한다.참고 안내
섹션 끝에서 관련 페이지로 안내할 때는 아래 패턴을 사용한다.링크 규칙
- 경로는 루트 상대 경로, 확장자 없이 작성한다:
/docs/build/versioning - 외부 링크는 전체 URL을 사용한다 (새 탭으로 자동 오픈).
6. 연관 검색어 섹션
AI 검색 엔진이 페이지를 정확히 찾을 수 있도록, 모든 페이지의 가장 아래에 연관 검색어 섹션을 넣는다.- 한국어 키워드와 영어 키워드를 쉼표로 나열한다.
- 사용자가 검색할 법한 동의어, 유사어, 약어를 포함한다.
- 본문에 등장하지 않는 관련 용어도 포함할 수 있다.
7. 문체와 품질 검수
작성 완료 후 아래 세 가지 skill을 순서대로 실행하여 검수한다.| 순서 | Skill | 목적 |
|---|---|---|
| 1 | /grammar-checker | 맞춤법, 띄어쓰기, 조사 오류 교정 |
| 2 | /style-guide | 용어 통일, 문체 일관성 확인 |
| 3 | /humanizer | AI 특유 패턴 제거, 자연스러운 문장으로 변환 |
문체 규칙
- 경어체(합쇼체) 를 사용한다: “~합니다”, “~하세요”
- 수동태를 피하고 능동태로 쓴다: “설정됩니다” → “설정하세요”
- 한 문장은 40자 이내로 짧게 끊는다.
- 불필요한 접속사(“또한”, “그리고”, “이를 통해”)를 줄인다.
용어 통일
| 통일 용어 | 사용하지 않는 표현 |
|---|---|
| 에이전트 | 봇, 챗봇, AI 어시스턴트 |
| 통화 기록 | 콜 로그, call log, 통화 로그 |
| 대시보드 | 콘솔, 관리자 페이지 |
| 워크스페이스 | 작업공간, workspace |
체크리스트
새 페이지를 작성하거나 기존 페이지를 수정할 때 아래를 확인한다.- vox.ai 표기가 올바른가
- 대시보드 설명에 이미지(또는 placeholder 주석)가 있는가
- 절차 설명에 Mermaid 다이어그램을 활용했는가
- 한영 병기 없이 한국어 또는 영어 하나만 사용했는가
- Mintlify 컴포넌트를 적절히 활용했는가
- 다른 페이지로 링크할 수 있는 용어에 내부 링크를 걸었는가
- 페이지 하단에 연관 검색어 섹션이 있는가
-
/grammar-checker→/style-guide→/humanizer검수를 완료했는가