vox.ai 문서 작성 규칙
이 문서는domains/voxai/docs/ 내 모든 MDX 페이지에 적용되는 작성 규칙이다.
새 페이지를 만들거나 기존 페이지를 수정할 때 반드시 따른다.
1. 브랜드 표기
- 서비스명은 vox.ai 로 표기한다 (대문자 X, 마침표 포함).
- “VOX”, “Vox”, “voxai” 등 다른 표기를 사용하지 않는다.
2. 시각 자료
페이지에 시각 자료를 적극 활용한다. 텍스트만으로 설명이 충분해도, 대시보드 화면이나 절차가 포함되면 반드시 시각 자료를 넣는다.이미지 규칙
/images/디렉토리에 저장한다.- 파일명은
섹션-설명.png형식으로 작성한다 (예:deploy-batch-campaign-dialog.png). - 아직 이미지가 없으면
{/* screenshot: 설명 */}주석을 남겨 위치를 표시한다.
Mermaid 규칙
- 코드 블록으로 삽입한다:
```mermaid - 노드 텍스트는 한국어로 작성한다.
- 3단계 이상의 절차, 분기가 있는 흐름에 사용한다.
3. 언어 원칙
한영 병기를 하지 않는다. 한국어 또는 영어 중 하나만 선택한다.4. Mintlify 컴포넌트 활용
MINTLIFY.md와 Mintlify MCP를 참고하여 best practice를 따른다.
필수 frontmatter
컴포넌트 선택 기준
5. 페이지 간 링크
내부 링크 적극 활용
문서에서 다른 페이지에서 이미 설명한 개념이 등장하면, 해당 단어를 내부 링크로 연결한다.참고 안내
섹션 끝에서 관련 페이지로 안내할 때는 아래 패턴을 사용한다.링크 규칙
- 경로는 루트 상대 경로, 확장자 없이 작성한다:
/docs/build/versioning - 외부 링크는 전체 URL을 사용한다 (새 탭으로 자동 오픈).
6. 연관 검색어 섹션
AI 검색 엔진이 페이지를 정확히 찾을 수 있도록, 모든 페이지의 가장 아래에 연관 검색어 섹션을 넣는다.- 한국어 키워드와 영어 키워드를 쉼표로 나열한다.
- 사용자가 검색할 법한 동의어, 유사어, 약어를 포함한다.
- 본문에 등장하지 않는 관련 용어도 포함할 수 있다.
7. 문체와 품질 검수
작성 완료 후 아래 세 가지 skill을 순서대로 실행하여 검수한다.문체 규칙
- 경어체(합쇼체) 를 사용한다: “~합니다”, “~하세요”
- 수동태를 피하고 능동태로 쓴다: “설정됩니다” → “설정하세요”
- 한 문장은 40자 이내로 짧게 끊는다.
- 불필요한 접속사(“또한”, “그리고”, “이를 통해”)를 줄인다.
용어 통일
체크리스트
새 페이지를 작성하거나 기존 페이지를 수정할 때 아래를 확인한다.- vox.ai 표기가 올바른가
- 대시보드 설명에 이미지(또는 placeholder 주석)가 있는가
- 절차 설명에 Mermaid 다이어그램을 활용했는가
- 한영 병기 없이 한국어 또는 영어 하나만 사용했는가
- Mintlify 컴포넌트를 적절히 활용했는가
- 다른 페이지로 링크할 수 있는 용어에 내부 링크를 걸었는가
- 페이지 하단에 연관 검색어 섹션이 있는가
-
/grammar-checker→/style-guide→/humanizer검수를 완료했는가