기술 문서의 목록 규칙

# 기술 문서에서 목록 구조화 규칙

목록은 정보를 정리하는 데 있어 선형 산문과 표 사이의 효과적인 균형을 이룹니다. 순서가 중요한 순차적 작업에는 번호 목록을 사용하세요: 설치 단계, 알고리즘. 엄격한 순서가 없는 항목 모음에는 순서 없는 목록을 사용하세요: 매개변수, 구성 요소.

목록 길이는 적당하게 유지하세요. 수백 줄에 달하는 목록은 스캔하기 어렵습니다—하위 섹션 또는 표로 나누세요.

안내를 위한 선행 문구

목록 앞에는 항상 목록 내용을 정의하는 선행 문구를 사용하세요. 이는 맥락을 제공하고 항목들을 연결합니다.

선행 문구 예시:

• 초기화를 위해 다음 작업을 수행하세요:
• 주요 함수 매개변수:
• 필요한 시스템 구성 요소:

이들을 구성하는 규칙:

• 통합 용어(작업, 매개변수, 단계)를 끝부분 가까이에 배치하세요.
• 항목 수를 명시하지 마세요—변경 시 오래될 수 있습니다.
• 특정 용어가 맞지 않으면 일반 용어를 사용하세요: 항목, 부분, 단계.

이렇게 하면 일관성을 보장하고 텍스트를 더 쉽게 스캔할 수 있습니다.

일관성을 위한 명사구

목록 항목을 명사구로 작성하세요. 이는 균일한 구조를 만들고 가독성을 높입니다. 예시 변환:

잘못된: 프로세스는 다음으로 구성됩니다: blanking, preparation, shipment.

올바른: 프로세스는 다음 단계로 구성됩니다: blanking, preparation, shipment.

모든 줄은 문법적으로 일관되어야 하며, 문장 조각과 완전한 문장을 섞지 마세요.

항목에서의 반복 피하기

목록 항목 시작에 반복되는 단어는 지루한 반복감을 줍니다. 공통 단어를 선행 문구로 옮기세요.

예시:

잘못된:

• Library A
• Library B
• Library C

올바른: 다음 라이브러리를 설치하세요:

• A
• B
• C

이렇게 하면 텍스트가 간결해지고 핵심 세부 사항에 초점이 맞춰집니다.

단일 항목 목록

하나의 항목만 있는 독립 목록은 일관성을 해치고 형식 오류처럼 보입니다. 항목을 선행 문구에 통합하세요.

예시: 'Input parameter: user_id'라고 쓰인 목록 대신 '입력 매개변수 user_id는 사용자 식별자입니다'라고 작성하세요.

목록의 구두점

일관성을 유지하세요:

• 대문자로 시작하는 줄은 마침표로 끝냅니다.
• 소문자로 시작하는 줄은 세미콜론으로 끝냅니다.

여러 단락으로 된 항목의 경우 첫 번째 스타일을 사용하세요. 이는 기술 문서 표준을 따릅니다.

중첩 목록 규칙

중첩은 계층 구조를 단순화하지만 엄격한 규율이 필요합니다.

번호 매기기 수준:

• 1단계: 1, 2, 3
• 2단계: 1.1, 1.2
• 3단계: 1.1.1, 1.1.2

문자와 로마 숫자는 피하세요—탐색을 복잡하게 합니다.

중첩 제한: 5단계 이하. 필요 시 하위 섹션으로 나누세요. 최적 가독성을 위해 4단계가 권장됩니다.

순서 없는 목록 후: 번호 매김을 재개하지 마세요. 번호 모호함을 피합니다.

문제 있는 구조 예시:

• 1단계

1.1. 2단계

- 순서 없음

1.1.1? // 불명확

주요 포인트

• 순서가 있는 경우에만 번호 목록 사용; 집합에는 순서 없는 목록.
• 통합 용어가 포함된 선행 문구 필수—수량 명시 금지.
• 명사구 사용 및 항목 반복 금지.
• 중첩 최대 5단계; 글머리 기호 후 번호 계속 안 함.
• 구두점: 대문자 줄은 마침표, 소문자 줄은 세미콜론.

목록은 문서, 가이드, 기사 같은 기술 텍스트의 스캔 용이성을 높입니다. 이 규칙을 따르면 중고급 개발자와 기술 전문가의 인지 부하를 최소화할 수 있습니다.

— Editorial Team