다음은 쓰리래빗츠가 문서를 작성할 때 준수하는 문서 작성 스타일 가이드입니다.

기본 원칙과 목적

목적(Purpose)

문서의 품질과 일관성을 확보하기 위한 작성 기준을 제공합니다.

적용 범위(Scope)

매뉴얼웍스로 작성하는 모든 문서에 적용합니다.

작성 원칙

간결하게, 명확하게, 정중하게

대상(Audience)

매뉴얼웍스를 사용하는 테크니컬 라이터와 제품 사용자(최종 독자)

스타일 및 톤 앤 매너(Voice & Tone)

말투

"~합니다(격식체)"를 기본으로 합니다.

태도

독자에게 전문적인 인상을 전달하는 것을 목표로 합니다.

시점

독자를 직접 지칭하지 않고 동작 중심으로 서술합니다(예: "클릭합니다").

문체

능동태를 사용하고, 한 문장은 간결하게 작성합니다.

용어

동일한 개념에는 동일한 용어를 일관되게 사용합니다.

동사 표현

동사 표현을 간결하고 명확하게 씁니다. 수동 표현은 능동으로 바꾸고, 복잡한 서술어는 단순하게 줄입니다.

기능을 설명할 때 '할 수 있습니다'는 대부분 '합니다'로 바꿀 수 있습니다.

단, 문맥상 어색하거나 선택 사항임을 명시해야 할 때는 그대로 씁니다.

간결한 문장

불필요한 표현을 줄여 문장을 간결하게 만듭니다.

• 형용사·부사 최소화: '매우', '다양한', '편하게', '구체적인' 같은 표현은 삭제합니다.

• 관계사 생략: '이를 통해', '그래서', '따라서'는 앞 문장과의 관계가 명확하면 생략합니다.

• 부가 설명 최소화: 독자가 이미 알 수 있는 내용은 쓰지 않습니다.

• 짧은 문장으로 나누기: 두 가지 이상의 내용을 하나의 문장에 담지 않습니다.

• 중복 줄이기: 같은 의미를 반복하지 않습니다.

문장 구조

목적어와 서술어는 가깝게 놓습니다. 목적어와 서술어 사이에 수식어구가 길면 독자가 문장을 이해하기 어렵습니다.

표기법 및 맞춤법 규정

맞춤법과 띄어쓰기

국립국어원 표준국어대사전을 기준으로 합니다.

표준국어대사전에 하나의 단어로 등재되어 있지 않아 띄어 쓰는 것이 맞지만, 전문 용어로 쓸 때 붙여 쓰기를 허용하는 용어 사례를 정리합니다.

기술 문서에서 자주 틀리는 맞춤법과 띄어쓰기 사례를 정리합니다.

기술 문서에서는 특히 다음 사항에 주의합니다.

• 조사 붙여 쓰기: 'API를', '서버에서', 'JSON으로'와 같이 영문 약어 뒤에도 조사는 붙여 씁니다.

• 단위와 숫자 띄어쓰기: '10 GB', '100 ms'와 같이 숫자와 단위 사이는 띄어 씁니다.

• 의존 명사 띄어쓰기: '설정할 때', '사용할 수 있는', '저장한 후'와 같이 의존 명사는 띄어 씁니다.

'한 번'과 '한번'은 의미에 따라 다르게 씁니다. 차례나 횟수를 나타낼 때는 띄어 씁니다. '시험 삼아', '어떤 기회에'의 뜻으로 '두 번' 등으로 바꿀 수 없을 때는 붙여 씁니다.

외래어 표기

국립국어원 외래어표기법을 기준으로 합니다.

IT 분야에서 자주 사용하는 외래어의 표준 표기를 정리합니다.

외래어 표기 시 다음 원칙을 따릅니다.

• 널리 통용되는 IT 용어는 국립국어원 표기를 우선하되, 업계 관행이 굳어진 경우 해당 표기를 허용합니다.

• 고유 명사(제품명, 서비스명 등)는 원어 그대로 표기합니다(예: GitHub, Kubernetes, Docker).

• 외래어 뒤에 한글 조사를 붙일 때는 외래어의 발음에 따라 조사를 선택합니다(예: '서버를', '클라우드에서').

숫자 및 단위 표기

숫자와 단위는 일관된 형식으로 표기합니다.

• 숫자와 단위 사이에는 공백을 둡니다: 16 GB, 100 ms, 3.5 GHz

• 천 단위 구분은 쉼표를 사용합니다: 1,000, 10,000, 1,000,000

• 버전 번호는 마침표로 구분합니다: 2.0, 3.1.4

• 포트 번호, IP 주소 등 기술적 숫자는 그대로 표기합니다: 포트 8080, 192.168.0.1

• 퍼센트는 숫자와 기호 사이에 공백 없이 표기합니다: 50%, 99.9%

문장 부호

기술 문서에서 문장 부호를 올바르게 사용하면 가독성이 높아집니다.

• 마침표(.): 모든 문장 끝에 마침표를 붙입니다. 목록 항목이 완전한 문장이면 마침표를 붙이고, 단어나 구이면 생략합니다.

• 쉼표(,): 나열할 때 항목 사이에 사용합니다. 마지막 항목 앞에는 쉼표를 넣지 않습니다(예: A, B, C).

• 괄호(()): 부연 설명이나 영문 원어를 병기할 때 사용합니다(예: 방화벽(firewall)).

• 꺾쇠괄호(<>): 사용자가 입력해야 할 값을 나타낼 때 사용합니다(예: <파일 이름>).

• 큰따옴표(""): 버튼이나 링크가 아닌 패널, 탭 이름 등 UI 요소의 이름을 나타낼 때 사용합니다(예: "태그" 패널, "이름" 열).

• 작은따옴표(''): 강조하거나 특정 용어를 지칭할 때 사용합니다(예: '멱등성'이란 동일한 요청을 여러 번 보내도 결과가 같은 성질을 말합니다).

전문 용어 표기

IT/기술 용어의 일관된 표기를 위한 규칙을 정합니다.

• 약어를 처음 사용할 때는 전체 이름과 약어를 함께 표기합니다(예: API(Application Programming Interface)).

• 이후에는 약어만 사용해도 됩니다.

• 코드, 명령어, 파일 이름 등은 고정폭 글꼴(monospace)로 표기합니다.

자주 사용하는 용어의 표준 표기를 다음과 같이 통일합니다.

우리말 표현

일본식 한자어나 번역체 표현 대신 자연스러운 우리말을 씁니다.

'~에 대해(서)'는 삭제하거나 직접 목적어로 바꿉니다. 다만 이렇게 바꿨을 때 문장이 어색해지면 교정하지 않습니다.

‘~의 경우(~할 때)’는 문맥상 의미 전달에 오차가 없고 어감의 미묘한 차이가 없을 때만 ‘~하면’으로 바꿀 수 있습니다.

'모든'이 앞에 올 때는 명사에 '들'을 붙이지 않습니다.

문서 서식(Formatting)

문서 구성

• 한 장에 너무 많은 내용을 담지 않습니다.

• 장이 많으면 부로 묶고, 그래도 많으면 문서를 분리합니다.

• 특별한 경우가 아니라면 제목 4와 제목 5 단락의 사용을 지양합니다.

텍스트 단락

• 헤드라인은 차례에 들어가지 않기 때문에 제한적으로만 사용합니다.

• 줄 바꿈 유지 단락은 본래 목적에 맞게 제한적으로만 사용합니다.

• 단순한 절차는 순서 목록으로 작성하고 복잡한 절차는 단계 단락으로 작성합니다.

절차 글쓰기와 개념 글쓰기

기술 문서의 내용은 절차(Task)와 개념(Concept)으로 구분합니다.

두 가지를 한 절에 섞지 않습니다. 개념 설명이 필요하면 절차 앞에 간략히 배치하거나 별도 절로 분리합니다.

절차와 단계 작성

절차를 설명할 때는 복잡도에 따라 단락 유형을 구분합니다.

절차를 작성할 때는 다음 원칙을 따릅니다.

• 각 단계는 동사로 시작합니다(예: "클릭합니다", "입력합니다", "선택합니다").

• 하나의 단계에는 하나의 행동만 포함합니다.

• 결과가 명확할 때는 단계 다음에 결과를 서술합니다(예: "저장 버튼을 클릭합니다. 파일이 저장됩니다.").

• 선택 사항이나 조건이 있는 단계는 그 사실을 명시합니다(예: "필요한 경우 ~를 설정합니다.").

코드와 명령어 표기

코드와 명령어는 목적에 따라 다음과 같이 구분하여 작성합니다.

코드를 작성할 때는 다음 사항을 지킵니다.

• 코드 단락에는 언어를 지정하여 하이라이트를 적용합니다.

• 사용자가 직접 입력해야 하는 값은 <값> 형식으로 표시합니다(예: <서버 주소>).

• 코드가 길거나 설명이 필요할 때는 코드 단락에 제목을 달아 맥락을 제공합니다.

• 출력 결과를 보여줄 때는 코드 단락을 사용하되, 제목에 "실행 결과"라고 명시합니다.

표 작성

표는 항목을 나열하거나 비교할 때 사용합니다.

표를 사용하기 적합한 경우는 다음과 같습니다.

• 3개 이상의 항목을 같은 기준으로 비교하는 경우

• 속성과 값을 쌍으로 정리하는 경우

• 옵션, 파라미터, 오류 코드 등 구조화된 참고 정보를 제공하는 경우

표를 작성할 때는 다음 원칙을 따릅니다.

• 표에는 항상 표 제목을 답니다.

• 열 헤더는 명사형으로 간결하게 작성합니다.

• 셀 내용이 없을 때는 "-" 또는 "해당 없음"으로 표시합니다.

• 하나의 열이나 행으로만 구성된 표는 목록으로 대체합니다.

• 표 안에 또 다른 표를 넣지 않습니다.

노트·팁·주의 사용 기준

본문 흐름 밖에서 추가 정보를 전달할 때는 노트, 팁, 주의 단락을 사용합니다. 세 가지를 다음 기준으로 구분합니다.

남용하면 독자가 무시하게 되므로 꼭 필요한 경우에만 사용합니다. 하나의 절에 같은 유형이 두 개 이상 나오면 본문으로 통합하는 것을 검토합니다.

시각 요소 활용

메뉴

메뉴는 <와 > 사이에 작성합니다. 다단계 메뉴는 |를 구분자로 사용하고, 앞뒤에 띄어쓰기를 합니다. 다음과 같이 메뉴라고 명시합니다.

<도구 | 웹 페이지> 메뉴를 클릭합니다.

버튼

텍스트 버튼은 버튼 문자 유형을 사용합니다. 다음과 같이 버튼이라고 명시합니다.

내용을 작성한 후 저장 버튼을 클릭합니다.

링크

링크는 <와 > 사이에 작성합니다. 다음과 같이 링크라고 명시합니다.

사용자를 추가하려면 <사용자 추가> 링크를 클릭합니다.

내부 문서 링크를 설정할 때는 특별한 경우가 아니라면 “링크 텍스트 유지하기”를 선택하지 않습니다.

코드 문자 유형으로 처리

다음 항목은 코드 문자 유형으로 처리합니다.

매뉴얼웍스를 시작하려면 3RABBITZ_HOME/bin 디렉터리로 이동합니다.

config.xml, server.properties

3RABBITZ_HOME/bin, /etc/hosts

ps -ef | grep java

true, false, null, UTF-8

JAVA_HOME, PATH

getUserList(), HttpServletRequest

/api/v1/users, /r/{controller}/{method}

8080, 443

인라인 주석

내용에 대한 부연 설명, 단어의 영문 병기 등을 괄호() 안에 작성하며, 이 괄호 안의 단어 또는 문장을 문자 유형 "인라인 주석"으로 표시합니다.

예: 마크 넣기(찾아보기 설정)

단락 안 그림

• 아이콘과 버튼 등 작은 이미지에만 사용합니다.

• SVG 형식 이미지는 PDF에 삽입할 수 없으므로 사용하지 않습니다.

• <리소스 | 단락 안 그림> 메뉴로 단락 안 그림을 체계적으로 관리하는 것을 권장합니다.

그림

그림은 텍스트만으로 설명이 어려운 UI, 구조, 흐름을 시각화할 때 사용합니다.

• 모든 그림에는 그림 제목을 답니다. 그림 제목은 그림 아래에 위치하며, 그림의 내용을 간결하게 설명합니다.

• 그림 제목이 본문에서 이미 충분히 설명된 경우에도 그림 제목을 생략하지 않습니다.

• 그림만으로 내용을 전달하지 않습니다. 본문에서 그림을 언급하거나 설명합니다.

• 해상도가 낮거나 텍스트가 깨지는 이미지는 사용하지 않습니다.

• 민감한 정보(계정 정보, 내부 서버 주소 등)가 포함된 화면은 가리거나 대체 이미지를 사용합니다.

콜아웃과 비주얼 에디터의 사용

• 이미지 및 도표: 그림 제목을 다는 방법과 이미지 정렬 방식을 일관되게 적용합니다.

• 색상 활용: 강조 텍스트에는 브랜드에서 지정한 색상(Hex code)을 사용합니다.

콜아웃은 그림의 특정 부분을 번호로 지칭하고, 그 아래 콜아웃 목록 단락에서 각 번호를 설명할 때 사용합니다.

콜아웃을 사용할 때는 다음 원칙을 따릅니다.

• 콜아웃 번호는 독자가 자연스럽게 읽는 순서(위에서 아래, 왼쪽에서 오른쪽)로 매깁니다.

• 콜아웃 목록의 각 항목은 간결하게 작성합니다. 긴 설명이 필요하면 본문에서 별도로 다룹니다.

• 콜아웃 번호는 1에서 10까지만 사용합니다. MS 워드 출력이 필요한 문서에서는 특히 주의합니다.