내용 작성 가이드

이 문서는 카카오디벨로퍼스 문서에 적용한 내용 작성 규칙을 설명합니다.
카카오디벨로퍼스는 문서에 일관된 내용 작성 규칙을 적용해, 대상을 간결하고 효율적으로 설명하기 위해 노력하고 있습니다.

시작하기 전에

체크리스트

내용 작성 가이드에 따라 문서를 올바르게 작성했는지 확인하기 위한 체크리스트입니다.

• 제목
  • 품사와 수준별 규칙을 적용했습니다.
  • 목차 구성을 고려해 작성했습니다.
• 본문의 첫 문장
  • 제목을 그대로 반복하지 않고, 두괄식으로 작성했습니다.
• 본문
  • 현재 시점의 능동태 문장으로 명확한 표현을 사용해서 짧게 작성했습니다.
• 용어
  • 한 가지 개념만 나타내도록 작성했습니다.
  • 부도덕한 용어를 사용하지 않았습니다.
• 목록과 표
  • 설명할 내용의 성격에 따라 서로 구분해서 사용했습니다.
• 이미지
  • 필요한 부분만 잘라 보조 자료로 사용했습니다.
• 부연 설명 박스
  • 용도를 구분해서 보조 자료로 사용했습니다.

문서 스타일

일관된 문서 스타일을 적용하면 내용을 더 쉽게 이해 가능하도록 문서를 작성할 수 있습니다. 카카오디벨로퍼스 문서에 적용된 스타일은 문서 스타일 가이드에서 확인할 수 있습니다.

좋은 예와 나쁜 예

아래는 이 문서에서 사용한 표현 예문 양식입니다.

제목

제목은 최대한 명확하게 작성합니다. 본문과 하위 제목을 대표하는 단어 또는 표현을 사용해 본문 내용이 요약될 수 있도록 합니다.

품사 규칙 적용하기

본문의 성격에 따라 동사 또는 명사형으로 제목 작성 규칙을 정하고 적용하면, 독자가 본문의 성격을 예측하는데 도움이 됩니다.

명사형 제목은 개념, 정보를 설명하는 내용 또는 하위 제목들을 묶는 상위 제목에 사용합니다. 하위 내용 또는 제목을 대표하면서 가장 구체적인 단어를 사용합니다.

동사형 제목은 사용자의 행동과 관련 내용에 사용합니다. 동사의 의미를 갖는 외래어(로그인, 로그아웃)는 그대로 사용합니다.

수준별 규칙 적용하기

하위 제목을 상위보다 더 자세하고 구체적으로 작성합니다.

같은 상위 제목을 갖는 하위 동일한 수준의 제목은 서로 같은 품사 규칙을 적용합니다. 아래 예시를 참고합니다.

• 제목
  • 품사 규칙 적용하기
  • 수준별 규칙 적용하기
  • 목차 구성하기
• 첫 문장
  • ...
• 본문
  • ...

하위 제목은 상위 제목에서 사용한 단어를 최대한 사용하지 않도록 작성합니다. 상위 제목: 하위 제목의 형태로 나열하면 자연스러운지 확인할 수 있습니다. 아래 예시를 참고합니다.

• 제목: 품사 규칙 적용하기
• 제목: 수준별 규칙 적용하기
• 제목: 목차 구성하기
• 첫 문장: ...

목차 구성하기

목차는 문서의 제목을 수준별로 구분해 나열한 목록으로, 문서의 전체 구조와 같습니다. 독자가 원하는 내용을 쉽게 찾을 수 있는 맥락과 문서의 모든 내용을 중복 없이 담을 수 있는 구성을 갖춰야 합니다. 각 항목을 특성을 고려해 문서 작성 초기 단계에서 구상합니다.

문서 내용을 변경해야 하는 경우 아래 항목을 함께 검토합니다.

• 내용을 수정한 문서의 제목, 또는 상위 제목까지 함께 변경해야 하는지
• 수정한 문서를 다른 상위 제목 아래로 옮겨야 하는지

한 가지 내용은 최선의 위치에 한 번만 작성하고 필요한 곳에 바로가기로 제공하면, 오류 발생 가능성과 유지 보수 부담을 줄일 수 있습니다. 반복이 발생하는 경우 아래 순서로 반복된 내용을 대체할 수 있는지 확인합니다.

➊ 단순 반복되어 한 번에 설명 가능한 경우, 한 항목으로 모아 작성하고 바로가기 제공

➋ 한 항목으로 설명할 수 없지만 같은 상위 제목을 가질 수 있는 경우, 한 제목 내 별도 항목으로 작성하고 바로가기 제공

➌ 많은 문서와 연관된 내용이거나, 문서 템플릿(Template)으로 인해 고정된 제목을 유지해야 하는 경우, 주요 내용을 별도로 작성하고 다른 문서에서 바로가기로 연결

첫 문장

제목을 그대로 반복하지 않기

본문은 제목에 대한 내용을 설명하기 때문에, 대부분의 경우 제목의 문구는 생략해도 자연스럽게 읽힙니다. 내용을 대표할 수 있는 제목을 정하고, 본문 첫 문장에서 그 의미를 설명하면 두괄식으로 작성할 수 있습니다.

두괄식으로 작성하기

문단의 첫 문장을 설명할 내용의 핵심 정보 또는 요약 문장으로 작성해 이어질 내용을 예상할 수 있도록 합니다. 이어서 첫 문장에 대한 부연 설명이나 추가 정보를 덧붙여 나갑니다.

문장의 앞부분에 대상을 명시해서 주제를 강조하고 독자가 쉽게 이해할 수 있도록 작성합니다.

본문

현재 시점으로 작성하기

문서는 설명 대상의 최신 상태 반영을 전제로 하기 때문에, 현재 시점으로 작성해야 문서의 수명을 늘리고 유지 보수 비용을 줄일 수 있습니다.

웹 페이지(Web Page) 문서는 설명 대상에 대한 한정 표현이 없고 접근 가능함이 최신 상태를 의미하므로, 현재 시점으로 작성합니다.

과거 항목(예: 구버전, 지원 종료 제품) 또는 특정 시점의 발행 문서(파일, 종이)는 설명 대상을 한정할 수 있는 요소(예: 버전, 릴리즈 날짜)를 내용에 포함하고 현재 시점으로 작성합니다.

미래를 가정하는 표현(예: 곧, 아마, -한다면)을 사용하지 않습니다. 이러한 표현이 필요한 내용은 변경 사항 반영 시점에 문서를 수정합니다.

능동태 문장으로 작성하기

능동태 문장으로 주어를 강조해 정보를 명확하고 간결하게 전달할 수 있도록 작성합니다. 수동태 문장은 주어가 생략되어 주체가 분명하지 않거나 불필요한 단어가 추가되어 복잡해질 수 있습니다.

대상을 행동보다 더 강조하거나, 주어를 알 필요가 없을 때에 한해 수동태를 사용합니다.

명확한 표현 사용하기

수치와 범위는 숫자와 국문 범위 표현(이상, 이하, 초과, 미만)을 사용해 작성합니다. 불확실한 표현(예: 많은, 적은, 대량, 소량)을 사용하지 않습니다.

비교 의미가 있거나 시간에 의존적인 표현(예: 새로운, 이전, 최신, 기존)은 한정된 대상(예: 버전, 릴리즈)을 설명할 때만 사용합니다. 이 경우, 대상을 한정할 수 있는 수치(예: 버전 번호, 릴리즈 날짜)와 참고 정보, 출처를 표기합니다.

대상의 범위를 설명할 때 생략 표현(예: -등, 특정, 기타)을 사용하지 않습니다. 대신 전체를 나열하거나 확인할 수 있는 바로가기를 제공합니다.

짧게 작성하기

한 문단이 하나의 주제만 다루도록 정보를 나눠 작성합니다. 한 문단은 세 줄 이하, 다섯 문장 이내로 작성합니다. 불필요한 단어 또는 문장을 최대한 줄이고 쉬운 단어를 사용해 정보 전달력을 높이도록 작성합니다.

용어

한 가지 개념만 나타내기

하나의 용어는 한 가지 개념만 나타내도록 정하고 문서 전체에서 일관되게 작성합니다.

부도덕한 용어 사용하지 않기

특정 인종, 집단, 종교에 대한 차별이나 비하의 소지가 있는 용어를 사용하지 않습니다.

목록과 표

목록(리스트, List)과 표(테이블, Table)는 모두 일정한 순서나 기준에 따라 내용을 나열하기 위해 사용합니다.

목록을 사용하면 항목간 계층 구조를 쉽게 전달할 수 있습니다. 같은 수준의 목록에 일관된 형식과 순서를 적용하면 가독성을 높일 수 있습니다. 목록은 순서가 없는 것과 있는 것으로 나뉩니다.

순서가 없는 목록은 아래의 경우에 사용합니다.

• 요약하거나 강조해야 하는 내용
• 두가지 이하의 공통 항목을 가진 비교적 간단한 내용

순서가 있는 목록은 아래의 경우 사용합니다.

1. 특정한 순서로 발생하는 단계나 단계의 집합 설명
2. 독자가 실제로 수행해야 하는 절차 안내

표는 행(row)과 열(column)로 구분한 기준에 맞춰 내용을 작성해야 합니다. 행은 논리적 순서로 정렬하거나, 설명 대상의 순서와 통일합니다. 논리적 순서가 없는 경우 사전순으로 정렬합니다.

표는 아래의 경우 사용합니다.

• 구성을 나타내거나 비교해야 하는 내용
• 세 가지 이상의 공통 항목을 갖는 비교적 복잡한 내용

이미지

독자의 이해를 돕기 위한 시각 자료로 이미지를 사용합니다. 이미지의 특정 부분을 표시하고 부연 설명할 수 있습니다. 아래 예시를 참고합니다.

🅐 앱 아이콘: 서비스 로고 또는 앱 아이콘으로 등록, 128*128 이하 크기 권장, 250KB 미만인 파일만 등록 가능 🅑 앱 이름: 서비스 이름 🅒 사업자명: 서비스의 사업자 이름

필요한 부분만 사용하기

이미지를 설명에 필요한 부분(예: 창, 메뉴)만 잘라서 사용합니다. 독자가 정보에 집중하는 것을 돕고, 설명 대상이 아닌 다른 부분의 변경으로 인한 불필요한 유지 보수 비용을 줄일 수 있습니다. 이미지에 개인 정보가 포함되지 않도록 주의합니다.

보조 자료로 사용하기

모든 내용은 이미지가 필요하지 않도록 본문에서 명확하게 설명해야 합니다. 이미지는 꼭 필요한 경우에만 이해를 돕는 보조 자료로 사용을 고려합니다.

부연 설명 박스

박스는 본문 내용에 대한 부연 설명을 위해, 독자의 주의를 환기시키거나 이목을 끌어야 하는 경우 사용합니다.

용도를 구분해 사용하기

부연 설명 박스는 보통 다른 색상의 배경이나 테두리로 강조합니다. 한 가지 유형의 박스는 언제나 같은 역할을 수행하도록 일관되게 사용해야 합니다.

박스를 남발할 경우 독자의 집중도를 흐트러뜨릴 수 있어, 필요할 때만 낮은 빈도로 사용합니다.

주의 사항 박스는 사용자가 오류나 문제를 겪을 수 있어 주의가 필요한 정보를 강조하여 전달할 때 사용합니다.

참고 정보 박스는 사용자의 이해를 돕기 위해 본문의 내용에 대한 부가 정보를 전달할 때 사용합니다.

보조 자료로 사용하기

모든 내용은 본문으로 전체 내용이 온전하도록 작성해야 합니다. 부연 설명 박스는 꼭 필요한 경우에만 목적에 따른 보조 자료로 사용을 고려합니다.