스타일 가이드

이 문서는 카카오디벨로퍼스 문서 스타일 가이드입니다.
카카오디벨로퍼스는 문서에 일관된 스타일을 적용해, 더 쉽게 이해 가능한 내용으로 작성하기 위해 노력하고 있습니다.

시작하기 전에

체크리스트

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

• 글자
  • 강조, 이미지 내 문구에 굵은 글꼴을 사용했습니다.
  • UI 요소에 대괄호([])를 사용했습니다.
  • 코드에 고정폭 글꼴을 사용했습니다.
• 용어
  • 표준어 규정에 따라 일관된 단어를 사용했습니다.
  • 용어별 최초 언급 시 작성 규칙을 지켜 작성했습니다.
  • 새로운 용어의 용어집 포함 여부를 확인하고 없는 경우 추가했습니다.
  • 사용한 외래어와 영문 용어는 대체 가능하고 자연스러운 국문 표현이 없음을 확인했습니다.
  • 외래어는 외래어 표기법을 지켜 작성했습니다.
  • 전문 용어는 본문에서 간략한 의미를 설명하고 참고 정보와 출처를 제공했습니다.
• 본문
  • 정해진 종결 표현, 문서 요소 지칭법을 지켜 작성했습니다.
  • 숫자, 날짜, 시간, 예시, 참고 정보, 출처 표기법을 지켜 작성했습니다.
• 기호는 정해진 항목만 사용했습니다.

내용 작성 규칙

일관된 내용 작성 규칙을 적용하면 대상을 더 간결하고 효율적으로 설명할 수 있습니다. 카카오디벨로퍼스 문서에 적용된 내용 작성 규칙은 문서 내용 작성 가이드에서 확인할 수 있습니다.

좋은 예와 나쁜 예

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

글자

굵은 글꼴(볼드 폰트, Bold font)을 사용해 단어 또는 문장을 강조하거나, UI, 이미지 내 문구를 언급할 때 가독성을 높입니다.

굵은 글꼴을 너무 많이 사용하면 오히려 가독성이 떨어집니다. 이 경우 아래의 대안을 사용합니다.

• 문단별 첫 언급 시에만 사용
• 일부 요소에 다른 강조 방식을 사용

고정폭 글꼴(Monospace font)을 코드, 데이터와 데이터 타입, 예제 코드에 사용합니다. 고정폭 글꼴을 사용해 비슷한 글자간 형태 차이, 글자 수 차이, 공백, 특수문자를 명확하게 표시합니다.

강조

단어 또는 문장을 굵은 글꼴을 사용해 강조합니다.

이미지 내 문구

이미지(Image) 속 문구에 굵은 글꼴을 사용해 그대로 언급했음을 표시합니다. 문구 내 자연스러운 설명을 위한 조사 추가 또는 삭제를 제한적으로 허용합니다. 아래 예시를 참고합니다.

UI(메뉴, 버튼)

UI(User Interface)에 대괄호([])를 사용해 그대로 언급했음을 표시합니다. 서로 관계를 갖는 요소는 > 기호를 사용합니다. 메뉴, 버튼과 같은 UI 요소명을 언급하지 않습니다.

코드

코드(Code)에 고정폭 글꼴을 사용해 그대로 언급했음을 표시합니다.

코드를 직접 지칭해 간결하게 작성합니다. 불필요한 수식어를 사용하지 않습니다.

예제 코드는 고정폭 글꼴을 사용해 본문과 구분된 서식 안에 작성합니다. 참고 설명은 주석으로, 생략한 코드는 온점 3개(...)로 표기합니다.

class GlobalApplication : Application() {
  override fun onCreate() {
    super.onCreate()

    // 다른 초기화 코드들
    ...

    // Kakao SDK 초기화
    KakaoSdk.init(this, "{NATIVE_APP_KEY}")
  }
}

바로가기

바로가기(링크, Link)는 본문에 URL을 할당해 다른 문서 또는 웹페이지와 연결하는 기능입니다. 바로가기임을 나타내는 일관된 글자 형식 적용을 권장합니다.

문구는 대상의 명칭, 제목과 같이 구체적으로 작성합니다.

용어

용어는 표준어 규정(참고: [외부 문서] 국립국어원 한국어 어문 규범)에 맞춰 국문으로 작성하는 것을 원칙으로 합니다. 외래어, 영문 용어, 약어, 전문 용어는 아래의 규칙에 맞게 사용합니다.

외래어

범용적으로 쓰이는 용어에 한해 외래어 표기법(참고: [외부 문서] 국립국어원 한국어 어문 규범)에 맞춰 국문으로 작성합니다. 외래어를 사용하기 전, 대체 가능하고 자연스러운 국문 표현이 있는지 확인하고 없는 경우 사용합니다.

최초 언급 시 괄호 안에 영문을 작성하고, 이후 국문만 사용합니다.

이해를 돕는 국문 용어가 있는 경우, 괄호 안에 영문과 해당 국문 용어를 쉼표(,)로 구분해 함께 작성합니다.

영문 용어

영문 용어를 사용하기 전, 대체 가능하고 자연스러운 국문 표현이 있는지 확인하고 없는 경우 사용합니다.

플랫폼, 프로그래밍 언어, 국문으로 표현이 어색한 영문 용어는 영문 그대로 작성합니다.

약어

국문 약어는 최초 언급 시 풀어 쓰고 괄호 안에 이하와 약어를 작성합니다. 이후 약어만 사용합니다.

영문 약어는 최초 언급 시 첫 글자만 대문자로 풀어 쓰고 괄호 안에 약어를 작성합니다. 이후 약어만 사용합니다.

영문 약어와 동일한 뜻의 국문 용어가 있는 경우, 최초 언급 시 괄호 안에 국문 용어와 영문을 쉼표(,)로 구분해 작성합니다. 이후 영문 약어만 작성합니다. 가능한 국문 용어 사용을 권장합니다.

영문 약어를 포함한 용어는 국문 단어와 영문 약어를 함께 사용합니다. 최초 언급 시 괄호 안에 전체 영문을 작성하고, 이후 국문 단어와 약어만 작성합니다.

전문 용어

독자에게 낯설거나 어려울 가능성이 있는 전문 용어는 참고 정보 또는 출처를 바로가기로 제공합니다. 이어지는 문장에서 간략한 의미를 설명하고, 별도의 용어집(참고: 카카오디벨로퍼스 용어집)으로 모아 관리하는 것을 권장합니다.

본문

종결 표현

서술형 문장은 니다. 로 마칩니다.

행동을 유도하는 문장은 합니다., 해야 합니다. 를 사용합니다. 하시기 바랍니다., 하십시오. 와 같은 격식체 또는 하세요. 와 같은 비격식체를 사용하지 않습니다.

목록과 표에선 개조식 문장을 사용합니다.

문서 요소 지칭

문서의 일부 요소(문단, 표, 이미지)를 가리킬 때 웹의 특성을 고려해 위, 아래를 사용합니다. 이전, 다음을 사용하지 않습니다.

숫자

아라비아 숫자로 작성합니다.

서술형 문장에서는 필요에 따라 국문(하나, 둘) 또는 서수(첫째, 둘째) 표현을 사용합니다.

4자리 이상의 숫자는 3자리마다 쉼표(,)를 사용합니다. (참고: 기호)

날짜와 시간

시간 단위(연월일시분)는 국문으로 작성합니다.

날짜와 시간 형식의 데이터는 괄호 안에 시간대와 형식을 쉼표(,)로 구분해 함께 표기합니다.

예시

괄호 안 또는 줄바꿈 후 예: 문구와 관련 예시를 작성합니다.

참고 정보와 출처

전문 용어 또는 추가 설명이 필요한 개념은 괄호 안에 참고: 문구와 참고할 자료 또는 출처의 제목을 바로가기로 작성합니다.

주석

이미지나 표와 같은 문서 요소의 내부에서 길거나 반복해서 설명해야 하는 경우 주석을 사용합니다. 아래 예시를 참고합니다.

Browser	Android	iOS	macOS	Windows	Linux
Chrome	O	O	O*	O*	O*
Edge	O	O	O	O*	O
Firefox	O	O	O	O	O
Safari	X	O	O	X	X

* 개발 및 디버깅(Debugging) 시 기본 브라우저(Default browser)

기호

아래 표에 작성된 기호만 용법에 맞춰 사용합니다.

기호	용법	예문
온점(.)	서술형 문장을 마칠 때 사용 공백( ) 없는 온점 3개로 생략한 코드 표현에 사용	카카오 로그인은 소셜 로그인 서비스입니다. ...
쉼표(,)	여러 단어나 문장을 나열할 때 사용 개조식 문장에서 앞 문장에 대한 부연 설명 시 사용 큰 단위 숫자 작성 시 세 자리마다 사용	카카오 로그인, 카카오싱크 초기값으로 고정, 예제 참고 3,000,000건
콜론(:)	부연 설명 시 사용, 앞은 붙이고 뒤는 띄어 씀 시간을 나타낼 때 사용	최대 개수: 99개 8:32
붙임표(-)	표 안에 기재할 내용이 없음을 표시하기 위해 사용 종결 표현 또는 조사를 표기하기 위해 사용	- 각 문장은 -니다.로 마쳐야 합니다.
괄호(())	용어와 문장을 추가 설명할 때 사용	키(Key), 회원번호(필수) 사용자에게 인증을 요청합니다. (참고: 인증 방법)
대괄호([])	UI 요소 언급 시 사용	[Redirect URI 등록]을 선택해 등록합니다.
꺾쇠괄호(<>)	닫는 괄호(>)를 관계 표현에 사용 괄호 용도로는 사용 안함	카카오 로그인 > 이해하기 > 기능 소개