[#how_to_write]
= 글쓰기 방법
Heywon Choi <heywon.choi@bankwareglobal.com>

[abstract]
.문서개요
--
이 문서는 매뉴얼 작성자가 일아야 할 {doctitle} 에 대한 기본적인 사항을 설명합니다.
--

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

* 상향식 목차 구성
  ** 생각나는 주제에 해당하는 소제목을 가급적 많이 작성한다.
  ** 관련 있는 소제목끼리 유형별로 분류하여 중간제목을 만든다.
  ** 중간제목을 모아 대제목을 만든다.
  ** 각 소제목의 문장을 써 나간다.
  ** 다시 읽어보고 필요하다면 제목 단위로 이동한다.
  ** 내용의 경중, 문장의 양에 따라 제목의 순위를 정한다. 전체 체계를 다시 정리한다.

* 하향식 목차 구성
  ** 큰 주제에 대해 논리적으로 수평축을 정한다.
  ** 수평축에 해당하는 각 항목마다 이를 뒷받침하는 하향식 소제목으로 구성한다.
  ** 각 소제목은 원인과 결과를 설명하는 과정이 된다.
  ** 각 수평축은 앞부분과 뒷부분이 상호 논리적인 흐름을 갖게 되므로 논리적 비약을 예방할 수 있다.

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

=== Plain Writing
* 긴문장 → 단문
* 수동태 → 능동태
+
----
~된다 → ~한다
----
* 능동적이고 긍정적인 표현으로 작성한다.
+
----
~안 된다 → ~된다
----
* 명확한 의미의 동작을 사용한다.
+
----
표4는 성공률과 에러율에 대한 목록이다. → 표4는 성공률과 에러율에 대해 설명하고 있다.
----
* 필요없는 말 생략(의미없는 표현 제거)
* 전문 용어 남발 주의
* 불필요한 설명 지양

=== 띄어쓰기
* 조사는 붙여 쓴다.
+
----
시스템은
----
+
* 의존 명사는 띄어 쓴다.
+
----
사용 중, 제품 표면에 돌출된 것 
----
* 단위를 나타내는 명사는 띄어 쓴다.
+
----
세 번째 시도하여
----
* 접사는 붙여 쓴다.
+
----
제1장, 오름차순 
----
* 열거할 때 사용하는 단어는 띄어 쓴다. “또는”이나 “및”과 같이 열거할 때 사용하는 단어는 띄운다.
+
----
사물 또는 사람 
----
* 보통명사나 부사로 굳어진 경우 붙여 쓴다.
+
----
그때 전원이 들어온다면 
----
* 보조 용언은 띄어쓴다.
+
----
이 경우에는 혼자 힘으로 알아 내어야만 한다.
----
* 복합 동사는 붙여 쓴다. 접미사 “~없다”는 붙여 쓰지만 형용사 “~없다”는 띄어 쓴다.
+
----
끊임없이 반복을 하는 경우 
----
* 전문 용어의 경우 붙여쓰기를 허용한다.
+
----
응용프로그램 
----
* 복합어(명+명)
복합어는 붙여 써도 되고 띄어 써도 된다. 해당 복합어가 일반적인 용어로 사용되는 경우는 붙여서 사용 한다. 단,영어+한글이 혼합되어 복합어가 되는 경우는 띄어 쓴다. 띄어쓰기로 결정된 단어는 모든 메시 지에 동일하게 띄어쓰기를 하고 붙여쓰기로 결정된 단어는 붙여서 사용한다.
+
----
이벤트코드(X) → 이벤트 코드(O) 
실행 시간(X) → 실행시간(O) 
환경 파일(X) →환경파일(O)
----
(예외 : 복합어 + 복합어 → 복합어 + ^ + 복합어, 명사 + 복합어 → 명사 + ^ + 복합어)

.상황별 띄어쓰기 원칙
[cols="21,19,60"]
|===
|case |Expected word |comment

|~중에
|~^중에
1.2+|"~중"은 의존명사이므로 띄어 쓴다. 동작동사 뒤에 오는 '중'과 '시'를 접미사로 보는 학자도 있지만 표준 국어대사전은 의존명사로 본다.

|~중입니다. |~^중입니다.

|~이상
|~^이상
|"~이상"은 독립된 형태로 사용되는 명사이므로 앞에 오는 단어와 띄어 쓴다. '동안', '따위', '여부', '이후', '아래', '내지', '대신', '너머', '사이', '다음' 등은 복합 명사를 만드는 예가 거의 없다. 따라서 이 단어들은 띄어쓴다.

|~후
|~^후
1.2+|"~후"는 명사이므로 앞에 오는 단어와 띄어 쓴다.

|~후에 |~^후에

|~^마다
|~마다
|"마다"는 조사이므로 앞에 오는 명사와 붙여뜬다. 예)연산이 발생할 때 마다(X) -> 연산이 발생할 때마다(O)

|~^별
|~별
|"별"은 접미사이므로 앞에 오는 명사와 붙여쓴다. 예) 운영체제 별(X) -> 운영체제별(O)

|재^~
|재~
|"재"는 접두사이므로 뒤에 오는 명사와 붙여쓴다. 예) 재 기동(X) -> 재기동(O)

|~데
|~데
1.2+a|"~데"는 붙여 써야 하는 경우와 띄어 써야 하는 경우가 있다.

① "~데"가 의존명사로 쓰인 경우는 띄어 쓴다. ("데"를 "일"이나 "것"으로 치환이 가능한 경우)

예) 분산 트랜잭션을 처리하는데 사용되는 XA(X) → 분산 트랜잭션을 처리하는 데 사용되는 XA(O)

위의 예는 "분산 트랜잭션을 처리하는 것에 사용되는 XA"로 바꿔도 무방하므로 띄어 쓴다.

② "~데"가 "ㄴ데"의 연결어미로 쓰인 경우는 붙여쓴다.

예) 환경변수로 데이터베이스를 생성하는 데 생성 이후(X) → 환경변수로 데이터베이스를 생성하는데 생성 이후 위의 예는 "~데"를 "것"으로 바꿔 쓸 수 없으므로 붙여 쓴다.

|~데 |~^데

|~지
|~지
1.2+a| "~지"도 붙여 써야 하는 경우와 띄어 써야 하는 경우가 있다. 
하지만 안내서에서는 띄어쓰는 경우가 거의 나타나지 않는다.

① "ㄹ지"의 연결어미로 쓰인 경우 붙여 쓴다.

예) 몇 블록씩 할당할지를 설정하는 파라미터이다.(O)

② "~지"가 의존명사로 쓰인 경우는 띄어써야 한다. 이 경우에 "지"는 "동안"의 의미이며, 안내서에서 사용되는 경우는 거의 없다.

③ 시간 경과를 나타내는 "~ㄴ 지"는 띄어 쓴다. 예) 시스템을 기동한 지

|~지 |~^지

|~^수록
|~수록
|예) 높은 레벨을 설정할수록 리스너에 더 많은 로그를 남긴다.(O) 예) 높은 레벨을 설정할수록 리스너에 더 많은 로그를 남긴다.(O)

|~^당
|~당
|"~당"은 접미사이므로 붙여 쓴다. 예) CPU당 스레드의 개수를 설정하는 파라미터이다.(O)

|비^~
|비~
|"비~"는 접두사이므로 붙여 쓴다. 예) 비 문자열, 비 이진 데이터(X) -> 비문자열, 비이진 데이터(X)

|~화^되다
|~화되다
1.2+|"~화"는 접미사이므로 앞에 오는 명사와 붙여 쓴다.
"~하다", "~되다"는 명사 뒤에 붙어 동사를 만드는 접미사이므로 명 사와 붙여 쓴다. 예) 초기화 하다(X) → 초기화하다(O), 초기화 되다(X) → 초기화되다(O)

|~화^하다 |~화하다

|~^받다
|~받다
|"~받다"는 피동을 뜻을 더하고 동사를 만드는 접미사이므로 붙여 쓴다. 예) 할당 받다(X) → 할당받다(O)

|~^부
|~부
|"~부"는 "부분"이나 "부문"의 뜻을 더하는 접미사이므로 붙여쓴다. 예) 처리 부, 선언 부(X) → 처리부, 선언부(O)

|제^~
|제~
|"제~"는 접두사이므로 붙여 쓴다. 예) 제 3세대 언어(X) → 제3세대 언어(O)

|**^입니다.
|**입니다.
a|"조사·어미 오류 서술격 조사 '이다'는 다음의 특성을 지닌다.

① 단독으로는 서술어가 될 수 없고 반드시 체언에 결합하여야 서술어가 된다.

② 모음으로 끝난 체언 뒤에서는 '이'가 생략될 수도 있다. 예) 나무이다, 나무다.

③ 서술격조사의 부정형 '아니다'는 형용사임에 주의한다.

④ '이다(아니다)'는 형용사와 흡사한 활용을 한다. 그러므로 '는다/ㄴ 다' 등과 결합할 수 없다.

⑤ 형용사와 다른 점은 '로'가 붙을 수 있다는 점이다. 예) 가을이로군, 좋은 책이 아니로군, *예쁘로군 "

|===

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

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

.문장부호 명칭
[cols="40,60"]
|===
|문장부호 |사용가이드

|*, 별표, 애스터리스크 |애스터리스크(*)
|, 쉼표, 콤마 |콤마(,)
|+, 더하기, 플러스, 크로스 |플러스(+)
|&, 앰퍼샌드, ampersand |앰퍼샌드(&)
|', 어퍼스트로피, apostrophe |apostrophe(')
|-, 하이픈 |하이픈(-)
|' ', 작은 따옴표, 작은따옴표 |작은따옴표(')
|" ", 큰 따옴표, 큰따옴표 |큰따옴표(")
|===

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

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

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

* 문장의 논리적 모순에 주의한다.
* ’최고’, ‘최대’ ,’완벽’, ‘매우 빠른 속도로’ , ‘상당히 많은’, ‘너무 고가의’ 등의 막연한 표현 대신 구체적인 수치를 제시한다.
+
----
"이 제품은 완벽한 솔루션입니다." 
→ "이 제품은 오류 1% 미만의 솔루션입니다."
----
* ‘그것은’, ‘이것은’ 등의 대명사 사용을 억제한다.
+
----
"또한 그것은 정기적으로 정보를 저장한다." 
→ "또한 (시스템)은 정기적으로 정보를 저장한다."
----
* 문장이 길어져서 너무 장황해지지 않도록 한다. 문장이 길어지는 경우 2문장으로 나누어서 표현하며 한 문장은 하나의 주제에 대해서만 기술한다.
* 단어는 쉬운 용어를 사용하고 일관성과 통일성을 유지한다.
+
----
“아파치를 설치한다.”, “Aparch의 사용에 있어서~” 등 한 문서 내에서 혼용된 경우 → “Aparch를 설치한다.”, “Aparch의 사용에 있어서~”
----
* 약어, 외래어, 전문용어는 표준화된 용어를 사용한다.
* 문장은 분명한 동작이나 메시지를 전달하도록 표현한다.
* 복문, 중문보다는 단문으로 표현한다. 장문과 단문이 적절히 균형을 이루고 문장간의 접속이 분명하도 록 한다.
* 주어, 술어의 문장 호응관계가 분명하도록 한다. 주어와 목적어는 반드시 포함한다.
* 가급적 다음 예와 같은 수동식 표현은 사용하지 않는다.
+
----
“~이 주목된다.”, “~으로 생각된다”, “~으로 여겨진다.”
----
* 다음 예와 같은 이중부정문 남용에 주의한다.
+
----
“~라고 하지 않을 수 없다.”, “~이 없는 것은 아니다.”
----
* 다음 예와 같은 추측 표현은 자제한다.
+
----
”~일 수도 있다.”, “~이 아닌 듯 하지만”
----
* 다음 예와 같은 대략적인 표현 대신 정확한 숫자로 표기한다.
+
----
”작년 봄에”, “매우 드물게”, “가끔씩”, “많은”, “적은”, “큰”, “작은”
----
* 다의적 용어나 이중적으로 해석될 수 있는 모호한 표현은 사용하지 않는다.
* 핵심주제를 첫머리에 기술한다. 가장 중요한 메시지를 가장 앞에 위치하고 다음 설명문에 부연설명을 한다. 문단구성 4요소 중 중요도에 해당한다.
* 제품명과 같은 고유명사는 영문으로 표시하고 영문 명사는 국문으로 표시한다.
+
----
아파치 → Apache
----
* 영문 약어는 대문자로 표기한다. 약어에 표시된 영어단어는 약어에 표시된 글자를 대문자로 하고, 이 외 에는 영어 단어의 첫 글자만 대문자로 표시한다. 단, 한글 용어를 표기해야 하는 경우, 원문 영어 약어와 풀이는 괄호 안에 쓴다.
+
----
XML (eXtensible Markup Language), 
HTML (HyperText Markup Language)
----
* 두문자어를 사용할 때 첫번째 언급에 약어를 풀어 쓰고, 이후에는 약어만 사용한다.
* 약어는 우리말 풀이 다음에 괄호 안에 약어와 원문을 병행 표기한다.
* 외래어 표기는 정부부처에서 제정한 외래어 표기법을 따른다.
+
----
Access → 액세스 (O), 접근 (X)
----

