[#how_to_write] = 글쓰기 방법 Heywon Choi <heywon.choi@bankwareglobal.com> include::ROOT:common_attrs.adoc[] [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) ----