글쓰기 방법

문서개요

이 문서는 매뉴얼 작성자가 일아야 할 글쓰기 방법에 대한 기본적인 사항을 설명합니다.

1. 문단 구성

매뉴얼의 실제적인 뼈대를 구성하는 단계이다. 사용자의 동작과 제품의 취급방법이 시계열의 흐름 속에서 설명되어야 하고, 제품의 각 기능에 대한 설명은 공간적 구성으로 이루어지며, 조작방법은 논리적인 순서를 따라 사례를 중심으로 구체적으로 설명해야 한다.

상향식 목차 구성
- 생각나는 주제에 해당하는 소제목을 가급적 많이 작성한다.
- 관련 있는 소제목끼리 유형별로 분류하여 중간제목을 만든다.
- 중간제목을 모아 대제목을 만든다.
- 각 소제목의 문장을 써 나간다.
- 다시 읽어보고 필요하다면 제목 단위로 이동한다.
- 내용의 경중, 문장의 양에 따라 제목의 순위를 정한다. 전체 체계를 다시 정리한다.
하향식 목차 구성
- 큰 주제에 대해 논리적으로 수평축을 정한다.
- 수평축에 해당하는 각 항목마다 이를 뒷받침하는 하향식 소제목으로 구성한다.
- 각 소제목은 원인과 결과를 설명하는 과정이 된다.
- 각 수평축은 앞부분과 뒷부분이 상호 논리적인 흐름을 갖게 되므로 논리적 비약을 예방할 수 있다.

2. 본문 작성

다음은 문단 구성을 완료하고 본문을 작성할 때 고려해야 할 사항이다.

2.1. Plain Writing

긴문장 → 단문
수동태 → 능동태
```
~된다 → ~한다
```
능동적이고 긍정적인 표현으로 작성한다.
```
~안 된다 → ~된다
```

명확한 의미의 동작을 사용한다.

표4는 성공률과 에러율에 대한 목록이다. → 표4는 성공률과 에러율에 대해 설명하고 있다.

필요없는 말 생략(의미없는 표현 제거)
전문 용어 남발 주의
불필요한 설명 지양

2.2. 띄어쓰기

조사는 붙여 쓴다.
```
시스템은
```

의존 명사는 띄어 쓴다.

사용 중, 제품 표면에 돌출된 것

단위를 나타내는 명사는 띄어 쓴다.
```
세 번째 시도하여
```
접사는 붙여 쓴다.
```
제1장, 오름차순
```
열거할 때 사용하는 단어는 띄어 쓴다. “또는”이나 “및”과 같이 열거할 때 사용하는 단어는 띄운다.
```
사물 또는 사람
```
보통명사나 부사로 굳어진 경우 붙여 쓴다.
```
그때 전원이 들어온다면
```

보조 용언은 띄어쓴다.

이 경우에는 혼자 힘으로 알아 내어야만 한다.

복합 동사는 붙여 쓴다. 접미사 “~없다”는 붙여 쓰지만 형용사 “~없다”는 띄어 쓴다.
```
끊임없이 반복을 하는 경우
```
전문 용어의 경우 붙여쓰기를 허용한다.
```
응용프로그램
```
복합어(명+명)
복합어는 붙여 써도 되고 띄어 써도 된다. 해당 복합어가 일반적인 용어로 사용되는 경우는 붙여서 사용 한다. 단,영어+한글이 혼합되어 복합어가 되는 경우는 띄어 쓴다. 띄어쓰기로 결정된 단어는 모든 메시 지에 동일하게 띄어쓰기를 하고 붙여쓰기로 결정된 단어는 붙여서 사용한다.
```
이벤트코드(X) → 이벤트 코드(O)
실행 시간(X) → 실행시간(O)
환경 파일(X) → 환경파일(O)
```
(예외 : 복합어 + 복합어 → 복합어 + ^ + 복합어, 명사 + 복합어 → 명사 + ^ + 복합어)

상황별 띄어쓰기 원칙
case	Expected word	comment
~중에	~^중에	"~중"은 의존명사이므로 띄어 쓴다. 동작동사 뒤에 오는 '중’과 '시’를 접미사로 보는 학자도 있지만 표준 국어대사전은 의존명사로 본다.
~중입니다.	~^중입니다.
~이상	~^이상	"~이상"은 독립된 형태로 사용되는 명사이므로 앞에 오는 단어와 띄어 쓴다. '동안', '따위', '여부', '이후', '아래', '내지', '대신', '너머', '사이', '다음' 등은 복합 명사를 만드는 예가 거의 없다. 따라서 이 단어들은 띄어쓴다.
~후	~^후	"~후"는 명사이므로 앞에 오는 단어와 띄어 쓴다.
~후에	~^후에	"~후"는 명사이므로 앞에 오는 단어와 띄어 쓴다.
~^마다	~마다	"마다"는 조사이므로 앞에 오는 명사와 붙여뜬다. 예)연산이 발생할 때 마다(X) → 연산이 발생할 때마다(O)
~^별	~별	"별"은 접미사이므로 앞에 오는 명사와 붙여쓴다. 예) 운영체제 별(X) → 운영체제별(O)
재^~	재~	"재"는 접두사이므로 뒤에 오는 명사와 붙여쓴다. 예) 재 기동(X) → 재기동(O)
~데	~데	"~데"는 붙여 써야 하는 경우와 띄어 써야 하는 경우가 있다. ① "~데"가 의존명사로 쓰인 경우는 띄어 쓴다. ("데"를 "일"이나 "것"으로 치환이 가능한 경우) 예) 분산 트랜잭션을 처리하는데 사용되는 XA(X) → 분산 트랜잭션을 처리하는 데 사용되는 XA(O) 위의 예는 "분산 트랜잭션을 처리하는 것에 사용되는 XA"로 바꿔도 무방하므로 띄어 쓴다. ② "~데"가 "ㄴ데"의 연결어미로 쓰인 경우는 붙여쓴다. 예) 환경변수로 데이터베이스를 생성하는 데 생성 이후(X) → 환경변수로 데이터베이스를 생성하는데 생성 이후 위의 예는 "~데"를 "것"으로 바꿔 쓸 수 없으므로 붙여 쓴다.
~데	~^데
~지	~지	"~지"도 붙여 써야 하는 경우와 띄어 써야 하는 경우가 있다. 하지만 안내서에서는 띄어쓰는 경우가 거의 나타나지 않는다. ① "ㄹ지"의 연결어미로 쓰인 경우 붙여 쓴다. 예) 몇 블록씩 할당할지를 설정하는 파라미터이다.(O) ② "~지"가 의존명사로 쓰인 경우는 띄어써야 한다. 이 경우에 "지"는 "동안"의 의미이며, 안내서에서 사용되는 경우는 거의 없다. ③ 시간 경과를 나타내는 "~ㄴ 지"는 띄어 쓴다. 예) 시스템을 기동한 지
~지	~^지
~^수록	~수록	예) 높은 레벨을 설정할 수록 리스너에 더 많은 로그를 남긴다.(O) 예) 높은 레벨을 설정할수록 리스너에 더 많은 로그를 남긴다.(O)
~^당	~당	"~당"은 접미사이므로 붙여 쓴다. 예) CPU당 스레드의 개수를 설정하는 파라미터이다.(O)
비^~	비~	"비~"는 접두사이므로 붙여 쓴다. 예) 비 문자열, 비 이진 데이터(X) → 비문자열, 비이진 데이터(X)
~화^되다	~화되다	"~화"는 접미사이므로 앞에 오는 명사와 붙여 쓴다. "~하다", "~되다"는 명사 뒤에 붙어 동사를 만드는 접미사이므로 명 사와 붙여 쓴다. 예) 초기화 하다(X) → 초기화하다(O), 초기화 되다(X) → 초기화되다(O)
~화^하다	~화하다
~^받다	~받다	"~받다"는 피동을 뜻을 더하고 동사를 만드는 접미사이므로 붙여 쓴다. 예) 할당 받다(X) → 할당받다(O)
~^부	~부	"~부"는 "부분"이나 "부문"의 뜻을 더하는 접미사이므로 붙여쓴다. 예) 처리 부, 선언 부(X) → 처리부, 선언부(O)
제^~	제~	"제~"는 접두사이므로 붙여 쓴다. 예) 제 3세대 언어(X) → 제3세대 언어(O)
**^입니다.	**입니다.	"조사·어미 오류 서술격 조사 '이다’는 다음의 특성을 지닌다. ① 단독으로는 서술어가 될 수 없고 반드시 체언에 결합하여야 서술어가 된다. ② 모음으로 끝난 체언 뒤에서는 '이’가 생략될 수도 있다. 예) 나무이다, 나무다. ③ 서술격조사의 부정형 '아니다’는 형용사임에 주의한다. ④ '이다(아니다)'는 형용사와 흡사한 활용을 한다. 그러므로 '는다/ㄴ 다' 등과 결합할 수 없다. ⑤ 형용사와 다른 점은 '로’가 붙을 수 있다는 점이다. 예) 가을이로군, 좋은 책이 아니로군, *예쁘로군 "

2.3. 문장 내 문장부호 언급

문장부호가 문장 내에서 언급되는 경우에는 다음과 같이 기술한다.

문장부호명(문장부호)

문장부호 명칭은 다음의 사용 가이드대로 표기한다.

문장부호 명칭
문장부호	사용가이드
*, 별표, 애스터리스크	애스터리스크(*)
, 쉼표, 콤마	콤마(,)
+, 더하기, 플러스, 크로스	플러스(+)
&, 앰퍼샌드, ampersand	앰퍼샌드(&)
', 어퍼스트로피, apostrophe	apostrophe(')
-, 하이픈	하이픈(-)
' ', 작은 따옴표, 작은따옴표	작은따옴표(')
" ", 큰 따옴표, 큰따옴표	큰따옴표(")

문장부호와 한글의 조합인 경우 띄어쓰기는 다음 규칙을 적용한다.

한글+괄호의 경우 붙여 쓴다.
```
테스트(test)
```
한글+콤마(,)+한글인 경우 앞 한글과는 붙이고 뒤 한글과는 띄어 쓴다.
```
테스트, 실행
```

2.4. 본문 작성시 고려사항

본문을 작성할 때에는 다음 사항을 고려해야 한다.

문장의 논리적 모순에 주의한다.
’최고’, ‘최대’, ’완벽’, ‘매우 빠른 속도로’, ‘상당히 많은’, ‘너무 고가의’ 등의 막연한 표현 대신 구체적인 수치를 제시한다.
```
"이 제품은 완벽한 솔루션입니다."
→ "이 제품은 오류 1% 미만의 솔루션입니다."
```

‘그것은’, ‘이것은’ 등의 대명사 사용을 억제한다.

"또한 그것은 정기적으로 정보를 저장한다."
→ "또한 (시스템)은 정기적으로 정보를 저장한다."

문장이 길어져서 너무 장황해지지 않도록 한다. 문장이 길어지는 경우 2문장으로 나누어서 표현하며 한 문장은 하나의 주제에 대해서만 기술한다.

단어는 쉬운 용어를 사용하고 일관성과 통일성을 유지한다.

“아파치를 설치한다.”, “Aparch의 사용에 있어서~” 등 한 문서 내에서 혼용된 경우
→ “Aparch를 설치한다.”, “Aparch의 사용에 있어서~”

약어, 외래어, 전문용어는 표준화된 용어를 사용한다.
문장은 분명한 동작이나 메시지를 전달하도록 표현한다.
복문, 중문보다는 단문으로 표현한다. 장문과 단문이 적절히 균형을 이루고 문장간의 접속이 분명하도록 한다.
주어, 술어의 문장 호응관계가 분명하도록 한다. 주어와 목적어는 반드시 포함한다.

가급적 다음 예와 같은 수동식 표현은 사용하지 않는다.

“~이 주목된다.”, “~으로 생각된다.”, “~으로 여겨진다.”

다음 예와 같은 이중부정문 남용에 주의한다.

“~라고 하지 않을 수 없다.”, “~이 없는 것은 아니다.”

다음 예와 같은 추측 표현은 자제한다.

”~일 수도 있다.”, “~이 아닌 듯 하지만”

다음 예와 같은 대략적인 표현 대신 정확한 숫자로 표기한다.

”작년 봄에”, “매우 드물게”, “가끔씩”, “많은”, “적은”, “큰”, “작은”

다의적 용어나 이중적으로 해석될 수 있는 모호한 표현은 사용하지 않는다.
핵심주제를 첫머리에 기술한다. 가장 중요한 메시지를 가장 앞에 위치하고 다음 설명문에 부연설명을 한다. 문단구성 4요소 중 중요도에 해당한다.
제품명과 같은 고유명사는 영문으로 표시하고 영문 명사는 국문으로 표시한다.
```
아파치 → Apache
```
영문 약어는 대문자로 표기한다. 약어에 표시된 영어단어는 약어에 표시된 글자를 대문자로 하고, 이 외 에는 영어 단어의 첫 글자만 대문자로 표시한다. 단, 한글 용어를 표기해야 하는 경우, 원문 영어 약어와 풀이는 괄호 안에 쓴다.
```
XML (eXtensible Markup Language),
HTML (HyperText Markup Language)
```
두문자어를 사용할 때 첫번째 언급에 약어를 풀어 쓰고, 이후에는 약어만 사용한다.
약어는 우리말 풀이 다음에 괄호 안에 약어와 원문을 병행 표기한다.
외래어 표기는 정부부처에서 제정한 외래어 표기법을 따른다.
```
Access → 액세스 (O), 접근 (X)
```