구조적 문서 작성하기 - 엄격한 기술 문서 작성 규칙 예시

기술 문서는 정확하고 명확하게 정보를 전달해야 하기 때문에, 구조적이고 일관된 문서 작성 규칙을 따르는 것이 좋습니다.

기본 규칙

• Markdown 문법을 사용합니다.

• 한국어로 상세하고 풍부한 설명을 제공합니다.
  • 기본적으로 ‘합니다체’를 사용합니다.
  • 명사형 문장이 더 적합한 경우에는 명사형 문장도 사용할 수 있습니다.
• 모든 문장은 반드시 마침표로 종료합니다.
  • 명사나 명사형 문장도 반드시 마침표로 종료합니다.
• 어려운 전문 용어가 등장하면, 용어에 대한 부연 설명을 따로 추가합니다.

문체 규칙

• 문장은 간결하고 명확하게 작성합니다.
  • 문장이 너무 길어지면, 문장을 나누어 각 문장이 하나의 개념만을 담도록 합니다.
  • 하나의 개념을 담는 문장이 인과 관계나 조건 관계로 이어져 길어지는 경우에는, 쉼표(,)로 구분하여 문장을 나눕니다.
    • ”~하기 때문에, ~합니다.”, “~한다면, ~합니다.”와 같이 인과와 조건 관계를 나타내는 문장은 쉼표로 구분합니다.
• 담백하고 무난한 문체를 사용합니다.
  • 더 쉽고 간결한 표현이 있다면, 그 표현을 사용합니다.
• ‘위와 같은’, ‘아래와 같은’, ‘다음과 같은’, ‘다음 단계로’, ‘다음 순서로’ 등의 표현은 사용하지 않습니다.
  • 하나의 문장은 그 문장 자체로 충분히 명확하게 설명되어야 하기 때문에, 지칭할 대상들을 함축하여 명확히 작성합니다.
  • 예를 들어, “Debezium은 다음과 같은 장점이 있습니다.”가 아니라, “Debezium은 data 손실이나 중복 없이 system 간 실시간 data 동기화가 가능하다는 장점이 있습니다.”로 작성합니다.
    • 각 장점의 상세한 내용은 하위 항목에 그대로 작성합니다.
• ‘이를 통해’, ‘이러한’ 등의 표현 대신, 더 명확하고 직접적인 표현을 사용합니다.
  • 예를 들어, “이를 통해 data의 완전성을 보장할 수 있습니다.”가 아니라, “snapshot을 통해 data의 완전성을 보장할 수 있습니다.”로 작성합니다.
• ”~할 수 있습니다.”, “~될 수 있습니다.” 등의 완곡한 표현을 남용하지 않습니다.
  • 꼭 필요한 경우에만 사용하고, 가능하면 “합니다.”, “됩니다.”와 같은 직설적인 표현을 사용합니다.
• 같은 개념에 대해 설명하는 경우라도, 다양한 표현을 사용하여 반복을 최소화합니다.
  • 특히, 같은 개념에 대해 연달아 설명할 때, 문장의 시작을 ‘~은’, ‘~는’으로 시작하지 않고 다양한 표현을 사용합니다.
• 문장은 colon(:)으로 끝나지 않습니다.
  • 모든 문장은 그 자체로 완결되어야 하며, 뒤따르는 표나 목록을 암시하는 형태로 끝나면 안 됩니다.
  • 나쁜 예 : “val과 const val의 차이점 :”.
  • 좋은 예 : “val과 const val은 값 결정 시점, 사용 가능 type, 선언 위치에서 차이가 있습니다.”.
• 문장 끝에 괄호로 부연 설명을 추가하지 않습니다.
  • 괄호로 끝나는 문장은 완결되지 않은 느낌을 줍니다.
  • 나쁜 예 : “val을 var로 override할 수 있습니다 (getter에 setter 추가).”.
  • 괄호 내용을 문장에 자연스럽게 녹이거나, 하위 항목으로 분리합니다.
    • 문장에 녹이기 : “val을 var로 override하면 getter에 setter가 추가됩니다.”.
    • 하위 항목으로 분리하기 : “val을 var로 override할 수 있습니다.” 다음 줄에 “getter만 있던 property에 setter가 추가됩니다.”를 하위 항목으로 추가합니다.

띄어쓰기 규칙

• 공식적인 한국어 띄어쓰기 규칙을 따릅니다.

• 붙여쓰는 것이 허용되는 경우에도, 띄우는 것이 원칙이라면 띄워 씁니다.

영어 단어 표기 규칙

• 영어가 원어인 단어는 한국어가 아닌 영어로 표기합니다.
  • 예를 들어, ‘데이터베이스’는 ‘database’로, ‘버튼’은 ‘button’으로 ‘업데이트’는 ‘update’로, ‘로그’는 ‘log’로, ‘버전’은 ‘version’으로, ‘시나리오’는 ‘scenario’로 표기합니다.
    • “데이터베이스는 데이터를 저장하고 관리하는 시스템입니다.”라는 문장은 “database는 data를 저장하고 관리하는 system입니다.”로 작성합니다.
  • 한글로 표현할 수 있는 단어는 영어로 작성하지 않습니다.
    • “automation 기술 역량 향상에는 effort가 필요합니다.”라는 문장은 “자동화 기술 역량 향상에는 노력이 필요합니다.”로 작성합니다.
      • ‘automation’은 ‘자동화’로, ‘effort’는 ‘노력’으로 표현할 수 있기 때문입니다.
    • “Performance Optimization Strategy”는 한글로 자연스럽게 표현 가능한 경우이므로 “성능 최적화 전략”으로 작성합니다.
• 첫 글자는 대명사만 대문자로 표기하고, 나머지는 소문자로 표기합니다.
  • 예를 들어, ‘데비지움’은 대명사이기 때문에 ‘Debezium’으로, ‘리눅스’는 대명사이기 때문에 ‘Linux’로, ‘시스템’은 대명사가 아니기 때문에 ‘system’으로 표기합니다.
• 문장을 시작하는 단어가 대명사가 아니라면 소문자로 시작합니다.
  • 예를 들어, “Database의 약어는 DB입니다.”라는 문장은 “database의 약어는 DB입니다.”로, “Table level lock으로 특정 table의 변경만 제한합니다.”는 “table level lock으로 특정 table의 변경만 제한합니다.”로, “Long transaction 관리 전략을 수립합니다.”는 “long transaction 관리 전략을 수립합니다.”로 작성합니다.
  • 반대로, “리눅스는 open source system입니다.”와 같이 대명사로 시작하는 문장은 “Linux는 open source system입니다.”로 작성합니다.
• 영어 단어에 한국어 접미사가 붙은 혼합 형태는 사용하지 않고, 완전한 영어로 표기합니다.
  • ‘token화’는 ‘tokenizing’으로, ‘index화’는 ‘indexing’으로 작성합니다.
  • 예를 들어, “검색어를 token화하고 stemming을 적용합니다.”는 “검색어를 tokenizing하고 stemming을 적용합니다.”로 작성합니다.
• 영어 용어가 처음 등장할 때, 괄호 안에 한글 용어를 병기할 수 있습니다.
  • 이후에는 영어 용어만 사용합니다.
  • 예를 들어, default parameter(기본 매개 변수)는 parameter에 기본값을 지정하는 기능입니다.로 작성하고, 이후에는 default parameter만 사용합니다.

한글 표기 vs 영어 표기

• 영어가 원어인 단어를 한글로 쓰면 안 됩니다.

대문자 표기 vs 소문자 표기

• 영어 단어의 대소문자는 위치(제목, table header, 본문)와 명사 종류(고유 명사, 일반 명사)에 따라 다르게 적용합니다.

• 본문에서 고유 명사는 대문자로 표기하고, 고유 명사가 아닌 일반 명사는 소문자로 표기합니다.

문장 구조화 규칙

• 모든 문장 앞에 - 를 넣어 항목화하고, 각 항목에는 하나의 문장만 들어가도록 합니다.
  • 제목(header)을 제외한 모든 문장에 적용되는 규칙입니다.
  • 단계에 대한 정의가 필요한 경우에는 ordered list를 사용하여 순서를 부여합니다.
• 계층적 list 구조를 사용합니다.
  • 주요 개념은 상위 항목으로 배치하고, 세부 설명은 하위 항목으로 배치합니다.
    • 상위 항목의 상위 개념은 포괄적이고 추상적인 내용으로, 하위 항목의 하위 개념은 구체적이고 실용적인 내용으로 구성합니다.
  • 예시나 추가 설명이 필요한 경우 항목의 하위 항목에 추가하여, 설명을 계층적으로 구조화합니다.
  • 상위 항목은 하위 항목들의 결론 또는 결과이고, 하위 항목은 상위 항목에 대한 설명 또는 원인입니다.
• 상위 항목과 하위 항목은 4칸 들여쓰기로 구분합니다.

제목 작성 규칙

• 제목은 기본적으로 명사형으로 작성하지만, 실행 방법이나 과정을 설명하는 경우 동명사형도 허용합니다.
  • 명사 : ‘확인’, ‘설정’, ‘사용’ 등.
  • 동명사 : ‘확인하기’, ‘설정하기’, ‘사용하기’ 등.

• 제목은 마침표로 끝내지 않습니다.

• 제목은 추상화 수준에 따라 1단계(#) 제목, 2단계(##) 제목, 3단계(###) 제목, 4단계(####) 제목을 사용합니다.
  • 1단계 제목은 문서 전체의 주제를 나타냅니다.
  • 2단계 제목은 1단계 제목의 세부 내용을 나타냅니다.
  • 3단계 제목은 2단계 제목의 세부 내용을 나타냅니다.
  • 4단계 제목은 3단계 제목의 세부 내용을 나타냅니다.
• 1단계 제목은 최상단에 위치하며 문서에서 한 번만 사용합니다.
  • 1단계 제목은 문서 전체의 주제를 나타내고, 문서는 하나의 주제만을 다루기 때문에, 문서 내에서 한 번만 사용합니다.
• 모든 제목은 반드시 하위 내용을 포함해야 합니다.
  • 제목 다음에 바로 다른 제목이 오는 것은 절대 금지됩니다.
  • 모든 제목 아래에는 최소 1개 이상의 항목화된 문장(- 로 시작)이 반드시 들어가야 합니다.
  • 하위 제목이 있는 경우에도, 상위 제목 바로 아래에 해당 section의 개괄 설명을 먼저 작성한 후 하위 제목을 배치합니다.
  • 제목 바로 아래의 개괄 설명은 추상적이거나 형식적인 문장이 아니라, 해당 section의 핵심 내용을 구체적으로 요약해야 합니다.
    • 나쁜 예 : “주요 field들로 구성됩니다.”, “다양한 방법을 소개합니다.”, “중요한 개념들을 다룹니다.”, “~하는 방법입니다.”, “~의 동작입니다.”, “~하는 pattern입니다.”, “다양한 기능을 제공합니다.”, “~의 특성을 비교합니다.”, “~할 때 주의할 점입니다.” 등.
    • 좋은 예 : “queryPlanner, executionStats, serverInfo 세 개의 최상위 field로 구성되며, 각각 실행 계획 정보, 성능 통계, server 정보를 담습니다.”, “aggregation pipeline은 $match(filtering), $group(집계), $project(field 선택), $sort(정렬) 등의 핵심 stage로 구성됩니다.” 등.
    • 추가 예시 : 하위 section에서 다루는 내용을 구체적으로 명시합니다.
      • “다양한 성능 최적화 기능을 제공합니다.” → “column family, Bloom Filter, block cache, compression 등의 기능으로 read/write 성능을 최적화합니다.”.
      • “LSM Tree와 B-Tree 기반 storage engine의 특성을 비교합니다.” → “LSM Tree는 write 성능과 space efficiency에서 우수하고, B-Tree는 read 성능에서 우수합니다.”.
      • “GTID 환경을 운영할 때 주의할 점입니다.” → “GTID 환경에서는 binary log 보관 기간, backup 복원 시 gtid_purged 설정, errant transaction 방지를 관리해야 합니다.”.
  • 개괄 설명은 독자가 하위 section들을 읽기 전에 전체 맥락을 이해할 수 있도록 작성합니다.
    • 주요 개념이나 구성 요소를 구체적으로 언급합니다.
    • 각 요소의 역할이나 목적을 간략히 설명합니다.
  • 제목 아래의 모든 문장은 - 로 항목화하여 작성합니다.
• 문서 작성 완료 후 모든 제목을 점검하여, 제목 바로 다음에 다른 제목이 오는 경우가 없는지 확인합니다.
  • 각 제목이 최소 1개 이상의 설명 항목을 포함하고 있는지 검증합니다.
• 제목은 ‘개요’, ‘특징’ 등과 같이 함축하지 말고, 표현력 있게 작성합니다.
  • 또한 ‘개요’와 같은 제목은 그 내용이 상위 제목 아래에 들어가면 의미가 통하기 때문에, 넣지 않습니다.
• 제목에는 별도로 강조 효과를 주지 않습니다.
  • 이미 제목 자체가 bold체로 표시되기 때문입니다.
• 제목에 들어가는 영어 단어들의 첫 글자는 대문자로 표기합니다.
  • 예를 들어, “git branch 관리”가 아니라 “Git Branch 관리”로 작성합니다.
  • 그러나 소문자로 표기하는 것이 더 일반적인 경우에는 소문자로 표기합니다.
• 제목에서도 명령어(command)는 backtick으로 감쌉니다.

전체 내용 구조화 규칙

• 전체적인 구성을 구조적으로 작성합니다.

두괄식 구성 규칙

• 내용의 전체적인 구조는 두괄식으로 구성합니다.
  • 결론이나 요약 내용이 글의 처음에 나오도록 하고, 뒤에는 부가적인 내용이 뒤따르게 합니다.
  • 따라서 글의 맨 뒤에 ‘결론’이나 ‘요약’ 부분이 없어도 됩니다.
• 글이나 단락의 시작 부분에 “~에 대해 알아보겠습니다.”, “~에 대해 설명하겠습니다.”, “~를 소개합니다.”와 같은 표현을 사용하지 않습니다.
  • 무언가를 설명하겠다고 예고하고 나중에 설명하는 것은 두괄식 작성 규칙에 어긋나기 때문입니다.
  • 대신 뒤에 나올 내용을 간략히 요약하여 먼저 알려주고, 자세한 내용은 이어서 말합니다.
  • “다음과 같은 특징이 있습니다.”와 같은 작성법을 지양하는 것과 같은 이유입니다.

단락 구분 규칙

• 글의 단락은 제목과 내용으로 구성됩니다.
  • 제목(#)은 해당 단락의 주제를 나타내고, 내용(- )은 해당 주제에 대한 설명을 제공합니다.
  • 제목이란 # 기호로 시작하는 header를 의미합니다.
  • 내용이란 - 기호로 항목화된 문장을 의미합니다.
• 1단계 제목으로 시작하는 단락은 1단계 단락, 2단계 제목으로 시작하는 단락은 2단계 단락, 3단계 제목으로 시작하는 단락은 3단계 단락, 4단계 제목으로 시작하는 단락은 4단계 단락이라고 부릅니다.
  • 각 단락은 하나의 주제를 중심으로 구성되어야 하며, 주제와 관련된 내용만 포함되어야 합니다.
• 1단계 단락은 문서의 전체 주제를, 2단계 단락은 1단계 단락의 세부 내용을, 3단계 단락은 2단계 단락의 세부 내용을, 4단계 단락은 3단계 단락의 세부 내용을 나타냅니다.
  • 1단계 단락은 2단계 단락을 포함하고, 2단계 단락은 3단계 단락을 포함하며, 3단계 단락은 4단계 단락을 포함합니다.
• 1단계 제목(#)에 대한 단락과, 2단계 제목(##)에 대한 단락은 ---로 구분합니다.
  • ---의 위와 아래에는 2개의 빈 줄을 추가하여, 내용을 더 명확히 구분합니다.
  • 마지막에 들어갈 참고 자료(## Reference) 단락도 2단계 제목이므로, ---로 구분합니다.

• 3단계 제목(###) 내용 단락은 위아래로 빈 줄 2개를 넣어 구분합니다.

• 4단계 제목(####) 내용 단락은 빈 줄 1개로 구분합니다.

도식 작성 규칙

• 도식(chart)이 필요한 경우엔 image를 사용하지 않고 Mermaid.js 문법을 사용하여 직접 그립니다.

• Mermaid.js chart에는 color style을 적용하지 않습니다.

• Mermaid.js chart는 node를 선언하는 선언부와 node를 사용하는 호출부를 나누어 작성합니다.
  • 선언부는 chart의 상단에 위치하고, 호출부는 chart의 하단에 위치합니다.
  • 약어를 남용하지 않고, node의 label은 명사형으로 간결하게 작성합니다.
• node ID는 lower_snake_case로 작성합니다.
  • node ID는 node_id[Label] 형식에서 node_id 부분을 의미합니다.
  • 나쁜 예 : A[Class A], G[God Object], M[Manager].
  • 좋은 예 : class_a[Class A], god_object[God Object], manager[Manager].

flowchart TD
    god_object[God Object]
    class_a[Class A]
    class_b[Class B]
    class_c[Class C]

    class_a --> god_object
    class_b --> god_object
    class_c --> god_object

Table 규칙

• header row와 body row의 구분자는 | --- |로 통일합니다.

• table 안에 들어가는 내용은 명사형 단어를 사용하며, 각 내용은 쉼표로 구분합니다.

• table의 각 항목 내용은 명사형 단어나 문장을 사용하며, 마침표로 끝내지 않습니다.

• table에서 row header 역할을 하거나 핵심 정보를 담은 column은 bold 처리합니다.

  • 예 : 항목명, 이름, 분류 등.

| 항목 | 설명 |
| --- | --- |
| **SPF** | 허용 발신 IP 목록 |
| **DKIM** | 전자 서명 |
| **DMARC** | 인증 정책 |

• table의 강조 column은 대부분 첫 번째 column이지만, 핵심 column이 다른 위치에 있을 수도 있으며, 이 경우에는 그 column을 bold 처리합니다.

| 단계 | 담당 | Protocol | 설명 |
| --- | --- | --- | --- |
| 1 | **MUA** | - | 사용자가 email 작성 |
| 2 | **MUA → MSA** | SMTP (587) | 인증 후 email 제출 |

| 조합 | 가능 여부 |
| --- | --- |
| 일반 index + 일반 index | **가능** |
| `$text` + 일반 index | **가능** (compound text index) |
| `$text` + `$near` | **불가** |
| `$text` + geospatial | **불가** |
| geospatial + geospatial | **불가** |

Highlight 규칙

• 내용 중 keyword나 중요한 내용은 bold체로 강조하며, 다른 강조 효과는 사용하지 않습니다.

• 각 문장의 핵심이 되는 부분을 강조 표시합니다.

특수 문자 규칙

• colon(:)의 앞과 뒤에는 공백을 하나씩 추가합니다.

• code와 수학 표기는 backtick으로 감쌉니다.
  • code block은 backtick 3개로 감싸서 표현합니다.
  • 실제 code에서 사용하는 class, function, keyword, annotation은 backtick으로 감쌉니다.
  • 수학 변수나 수식(x, y = x + 1, n² 등)은 backtick으로 감쌉니다.
  • Big O 표기법(O(1), O(n), O(log n) 등)은 backtick으로 감쌉니다.
  • 개념적 용어(scope, buffer, handler, pattern 등)는 backtick 없이 작성합니다.
• emoticon을 사용하지 않습니다.
  • ✓, ✗, ⚠️, 🎯 등의 emoticon은 기술 문서의 전문성을 해치기 때문에 사용하지 않습니다.
  • 대신 명확한 text 표현을 사용합니다.
    • “✓ 좋음” → “좋은 예”, “권장” 등.
    • “✗ 나쁨” → “나쁜 예”, “비권장” 등.
    • “⚠️ 주의” → “주의”, “경고” 등.

참고 자료 표기 규칙

• 참고한 자료는 제일 하단에 “Reference”라는 2단계 제목 영역에 표기(## Reference)합니다.

• 대체 text 없이 외부 link가 바로 표시되도록 - <reference.link.com/some_uri> 형식으로 작성합니다.

자연스러운 문체 규칙

• 기계적으로 번역한 것처럼 느껴지지 않도록, 자연스러운 한국어 문체를 사용합니다.

번역투 표현 피하기

• 영어에서 직역된 듯한 어색한 표현을 피하고, 자연스러운 한국어 표현을 사용합니다.
  • ”~를 제공합니다”, “~를 달성합니다”, “~를 구현합니다” 등의 어미를 반복 사용하지 않습니다.
    • 같은 어미가 여러 문장에 연달아 나오면 기계적으로 번역한 듯한 느낌을 줍니다.
    • 나쁜 예 : “완전성을 제공합니다.”, “안정성을 제공합니다.”, “확장성을 제공합니다.” 등.
    • 좋은 예 : “완전성을 보장합니다.”, “안정적으로 동작합니다.”, “확장 가능합니다.” 등.
  • 문맥에 따라 가장 자연스러운 표현을 선택합니다.
    • “data의 완전성을 제공합니다.” → “data의 완전성을 보장합니다.”.
    • “포괄적인 지원을 제공합니다.” → “포괄적으로 지원합니다.”.
    • “최적화된 성능을 달성합니다.” → “최적화된 성능을 보장합니다.”.
    • “세 가지 결과를 반환합니다.” → “세 가지 결과를 반환합니다.” (이 경우는 자연스러움).

사용하지 않는 표현들

• 지시 표현은 절대 사용하지 않습니다.
  • 사용 금지 : ‘이를 통해’, ‘이러한’, ‘다음과 같은’, ‘위와 같은’, ‘아래와 같은’ 등.
• 반복되는 번역투 어미의 사용을 피하고, 사용하더라도 연속해서 반복 사용하지 않습니다.
  • 적절한 빈도로 사용 : ‘제공합니다’, ‘달성합니다’, ‘구현합니다’ 등.
  • 한 문단에 같은 어미가 3번 이상 나오지 않도록 합니다.
• 예고 표현은 절대 사용하지 않습니다.
  • 사용 금지 : “~에 대해 알아보겠습니다”, “~를 소개합니다”, “~를 설명하겠습니다”, “~를 다룹니다” 등.
• 완곡 표현을 남용하지 않고, 꼭 필요한 경우에만 사용합니다.
  • 필요한 경우에만 사용 : “~할 수 있습니다.”, “~될 수 있습니다.” 등.

문서 작성 완료 후 검증 Check List

• 모든 제목 아래에 최소 1개 이상의 항목화된 설명이 있는가?
  • 제목 바로 다음에 다른 제목이 오지는 않는가?
• 제목 바로 아래의 설명이 구체적이고 명확한가?
  • 해당 section의 핵심 내용을 요약하고 있는가?
• ‘제공’, ‘달성’ 등의 번역투 어미가 과도하게 반복되지 않았는가?
• ‘이를 통해’, ‘다음과 같은’ 등의 지시 표현이 사용되지 않았는가?
• 영어 단어 표기 규칙이 일관되게 적용되었는가?
• colon(:) 앞뒤에 공백이 있는가?
• 문장이 자연스럽고 읽기 편한가?

Reference

• https://www.simin.im/notes
• https://devocean.sk.com/blog/techBoardDetail.do?ID=165343&boardType=techBlog