2025년 6월 17일 작성

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

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

기본 규칙

  • Markdown 문법을 사용합니다.

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

문체 규칙

  • 문장은 간결하고 명확하게 작성합니다.
    • 문장이 너무 길어지면, 문장을 나누어 각 문장이 하나의 개념만을 담도록 합니다.
    • 하나의 개념을 담는 문장이 인과 관계나 조건 관계로 이어져 길어지는 경우에는, 쉼표(,)로 구분하여 문장을 나눕니다.
      • “~하기 때문에, ~합니다.”, “~한다면, ~합니다.”와 같이 인과와 조건 관계를 나타내는 문장은 쉼표로 구분합니다.
  • 담백하고 무난한 문체를 사용합니다.
    • 더 쉽고 간결한 표현이 있다면, 그 표현을 사용합니다.
  • “위와 같은”, “아래와 같은”, “다음과 같은”, “다음 단계로”, “다음 순서로” 등의 표현은 사용하지 않습니다.
    • 하나의 문장은 그 문장 자체로 충분히 명확하게 설명되어야 하기 때문에, 지칭할 대상들을 함축하여 명확히 작성합니다.
    • 예를 들어, “Debezium은 다음과 같은 장점이 있습니다.”가 아니라, “Debezium은 data 손실이나 중복 없이 system 간 실시간 data 동기화가 가능하다는 장점이 있습니다.”로 작성합니다.
      • 각 장점의 상세한 내용은 하위 항목에 그대로 작성합니다.
  • “이를 통해”, “이러한” 등의 표현 대신, 더 명확하고 직접적인 표현을 사용합니다.
    • 예를 들어, “이를 통해 data의 완전성을 보장할 수 있습니다.”가 아니라, “snapshot을 통해 data의 완전성을 보장할 수 있습니다.”로 작성합니다.
  • “~할 수 있습니다.”, “~될 수 있습니다.” 등의 완곡한 표현을 남용하지 않습니다.
    • 꼭 필요한 경우에만 사용하고, 가능하면 “합니다.”, “됩니다.”와 같은 직설적인 표현을 사용합니다.
  • 같은 개념에 대해 설명하는 경우라도, 다양한 표현을 사용하여 반복을 최소화합니다.
    • 특히, 같은 개념에 대해 연달아 설명할 때, 문장의 시작을 “~은”, “~는”으로 시작하지 않고 다양한 표현을 사용합니다.

띄어쓰기 규칙

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

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

틀린 표기 옳은 표기
건의사항 건의 사항
경력사항 경력 사항
변경사항 변경 사항
결정사항 결정 사항
고려사항 고려 사항
공지사항 공지 사항
권고사항 권고 사항
권장사항 권장 사항
문의사항 문의 사항
개선방안 개선 방안
기대효과 기대 효과
유지보수 유지 보수
유지보수성 유지 보수성

영어 단어 표기 규칙

  • 영어가 원어인 단어는 한국어가 아닌 영어로 표기합니다.
    • 예를 들어, ‘데이터베이스’는 ‘database’로, ‘버튼’은 ‘button’으로 ‘업데이트’는 ‘update’로, ‘로그’는 ‘log’로 표기합니다.
      • “데이터베이스는 데이터를 저장하고 관리하는 시스템입니다.”라는 문장은 “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입니다.”로 작성합니다.

문장 구조화 규칙

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

제목 작성 규칙

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

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

  • 제목은 추상화 수준에 따라 1단계(#) 제목, 2단계(##) 제목, 3단계(###) 제목, 4단계(####) 제목을 사용합니다.
    • 1단계 제목은 문서 전체의 주제를 나타냅니다.
    • 2단계 제목은 1단계 제목의 세부 내용을 나타냅니다.
    • 3단계 제목은 2단계 제목의 세부 내용을 나타냅니다.
    • 4단계 제목은 3단계 제목의 세부 내용을 나타냅니다.
  • 1단계 제목은 최상단에 위치하며 문서에서 한 번만 사용합니다.
    • 1단계 제목은 문서 전체의 주제를 나타내고, 문서는 하나의 주제만을 다루기 때문에, 문서 내에서 한 번만 사용합니다.
  • 모든 제목은 반드시 하위 내용을 포함해야 합니다.
    • 제목 다음에 바로 다른 제목이 오는 것은 절대 금지됩니다.
    • 모든 제목 아래에는 최소 1개 이상의 항목화된 문장(- 로 시작)이 반드시 들어가야 합니다.
    • 하위 제목이 있는 경우에도, 상위 제목 바로 아래에 해당 section의 개괄 설명을 먼저 작성한 후 하위 제목을 배치합니다.
    • 제목의 개괄 설명은 해당 section에서 다룰 내용을 2-3개 항목으로 요약하여 제시합니다.
    • 제목 아래의 모든 문장은 - 로 항목화하여 작성합니다.
  • 문서 작성 완료 후 모든 제목을 점검하여, 제목 바로 다음에 다른 제목이 오는 경우가 없는지 확인합니다.
    • 각 제목이 최소 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개로 구분합니다.

도식 작성 규칙

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

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

  • Mermaid.js chart는 componenet를 선언하는 선언부와 componenet를 사용하는 호출부를 나누어 작성합니다.

    • 선언부는 chart의 상단에 위치하고, 호출부는 chart의 하단에 위치합니다.
    • 약어를 남용하지 않고, component의 이름은 명사형으로 간결하게 작성합니다.
    • component 식별값은 lower snake case로 작성합니다.

Table 규칙

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

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

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

Highlight 규칙

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

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

특수 문자 규칙

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

  • code 성격의 단어는 backtick으로 감싸고, code block은 backtick 3개로 감싸서 표현합니다.

참고 자료 표기 규칙

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

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

  • 작성 요청과 함께 참고 자료를 제공받은 경우에는 제공받은 link를 참고하고 출처 link를 추가합니다.

    • 또는 스스로 참고한 link가 있다면, 해당 참고 자료의 link를 추가합니다.

Reference

목차