Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Star 40 You must be signed in to star a gist
  • Fork 10 You must be signed in to fork a gist
  • Save 9beach/41b8b51b13e4704653a8 to your computer and use it in GitHub Desktop.
Save 9beach/41b8b51b13e4704653a8 to your computer and use it in GitHub Desktop.
기술 문서를 쓸 때 주의해야 할 몇 가지를 나열합니다.

기술 문서를 쓸 때 주의해야 할 몇 가지

독자 배려

자신의 생각과 할 일을 정리하는 것이 기술 문서의 목표가 될 수는 없다. 먼저 독자를 식별하라. 그리고 독자를 배려하고 독자 입장을 생각하며 문서를 작성하라.

텍스트 파일의 장점

중요한 정보를 위키나 깃(Git)에서 텍스트로 작성하지 않고, 워드나 파워포인트 같은 이진 문서로 작성할 때마다 당신의 동료는 접근성, 가시성, 버전 관리 등 다양한 문제로 고생할 것이다.

명징한 소재

잡다한 소재가 하나의 글에 다 들어가 있으면 다듬기도 힘들고 딴 데 활용하기도 힘들다. 자기 완결적인 글로 나누면 정보로서 가치가 커진다. 나중에 나눌 의향으로 일단 쓰는 것은 좋다. 고민하면서 글쓰기를 미루는 것보다 낫다.

단락 나누기

마침표가 나올 때마다 무분별하게 줄을 바꾸지 않는다. 단락 나누기 개념에 유의하라.

리스트를 남용하지 않는다. 온전한 문장들로 구성된 단락을 선호하라. 열거될 대상을 규정하는 온전한 문장이나 제목이 선행할 때만 제한적으로 리스트를 사용한다.

제목의 구조

제목만 뽑아서 읽어도 내적 논리를 발견할 수 있어야 한다. ‘의식의 흐름’대로 썼다면 논리를 발견하기 힘들 것이다. 좋은 문서를 찾아서 참고하라.

도입부

(O) 커버로스는... 컴퓨터 네트워크 인증 프로토콜이다.
(X) 커버로스는... 보안을 위해 만들어졌다.

두괄식이 무조건 좋은 것은 아니지만 도입부를 정의로 시작하는 것은 괜찮은 선택이다.

배경, 목적, 범위

왜 글을 쓰는지 독자도 안다고 가정하지 말라. 배경, 목적, 범위 등을 생략한 채 곧장 하고 싶은 말이나 결론만 정리한다면, 일반에게 공유하기에는 부적당한 회의록이나 넋두리 수준의 글이 될 것이다.

외국문자와 한글의 혼용

결론부터 말하면, 외국문자와 한글의 혼용을 허락하는 존중할 만한 교열 정책은 존재하지 않는다. 즉 ‘합의했다’ 대신 ‘컨센서스를 이루었다’라고 쓴다면 권하기는 힘들지만 틀리지는 않았다. 그러나 ‘Consensus를 이루었다’라고 쓴다면 틀렸다. ‘IBM’ 같은 약어나 상호가 아니라면 ‘클라우드 컴퓨팅’, ‘아파치 하둡’ 같이 한글로 써야 한다.

고유 명사든 최신 기술 용어든 모조리 한글로 쓰는 것은 상식적이고 온건한 방식이다. “東京에서 London를 거쳐 तमिल नाडु로 떠났다.”라고 쓸 수도 없고 “Tokyo에서 London을 거쳐 Tamil Nadu로 떠났다.”라고 쓸 수도 없다. 전자는 논리적으로 말은 되지만 현실적으로 문제가 많고 후자는 말이 안 된다. 그래서 “도쿄에서 런던을 거쳐 타밀 나두로 떠났다.”라고 써야 한다. “I went to 서울 last year.”라고 쓰는 미국인이 있는지, “Jag åkte till 서울 förra året.”라고 쓰는 스웨덴인이 있는지 생각해보라. 현지의 발음을 존중해서 자국어로 쓰는 것은 세계 곳곳에서 합의되고 검증된 방식이다.

(O) 합의했다.
(△) 합의를 이루었다.
(△) 컨센서스를 이루었다.
(X) Consensus를 이루었다.
(O) 도쿄에서
(X) 東京에서
(△) 동경에서
(O) 도쿄(東京)에서
(O) 런던(London)에서
(O) 런던에서
(X) London에서

예외 없이 한글로 쓰기로 했다면, 외국 문자를 괄호 없이 이어 써도 병기할 뜻이 드러나므로 문제없다. 많이 쓰는 표기법이다.

(O) 런던London에서
(O) 도쿄東京에서

보편적인 소재의 글

‘깃헙 풀 리퀘스트 사용법’, ‘맵 리듀스의 이해’ 등 보편적인 소재로 글을 쓰려면 그에 걸맞은 전략이 필요하다. 단순 번역이나 요약은 가치가 작다. 구체적인 술어나 한정사로 주제를 구체화하라. 특별한 목표나 시각, 전략이 없다면 굳이 새로 쓰지 말고 좋은 글에 링크하는 편이 나을 것 같다.

제목의 변별력

‘준비물’보다 ‘2018년 용산 청소년 캠프 참가자 준비물’이 낫다.

제목의 어법

Tip: Installing Samba -> Installing Samba Tip
HOWTO: Installing Apache -> How To Install Apache
연구과제: 한국의 도시 빈민 실태 -> 한국의 도시 빈민 실태 연구
연구과제: 한국의 도시 빈민 실태 -> 한국의 도시 빈민 실태

제목에 즉흥적으로 지어낸 자신만의 체계를 반영하는 것은 특권을 요구하는 것과 마찬가지다. 보편적인 어법에 맞추도록 노력하라.

속성, 범주 등 임의로 지어낸 메타 정보를 제목에 넣고 싶어서 자연스러운 어법을 깨는 경우가 많다. 위키에서 글은 전체 위키 공간의 일부이다. 위키 글 하나는 관계(링크) 속에서 다양하게 위치하며 규정된다. 작성 당시 자신만의 특수한 맥락(가령 팁과 하우투를 정리 중이라거나)으로 글을 속박하는 것은 좋지 않다. 동의받지 않은 자신의 체계를 타인에게 노출하는 미성숙한 행위로 비난받을 수 있다. Tip, HOWTO, 연구과제와 같은 글머리를 넣고 싶다면 먼저 동료들과 전체 글머리 체계를 합의해야 할 것이다.

중복

의미가 작거나 중복인 말은 없애는 편이 낫다.

말하는 것보다 침묵하는 것이 낫다 -> 말보다 침묵이 낫다
산다는 것의 의미 -> 사는 의미
예술가가 될 수 있는 가능성 -> 예술가가 될 가능성
축구에 관해 이야기하자 -> 축구 이야기하자
축구공을 가지고 멀리차기 놀이를 -> 축구공 멀리차기 놀이를
서버 설치법을 설명한다 -> 서버 설치를 설명한다
실수로 인해 -> 실수로
죽게 되고 -> 죽고
알려져 있는 -> 알려진
알려 줍니다 -> 알립니다
꼭 필요한 -> 필요한

맞춤법

맞춤법이 엉망인 글은 신뢰하기 힘들다. 자동 맞춤법 검사기를 활용하라.

인용부호

큰따옴표와 작은따옴표의 용도는 모두 잘 알 것이다. 인용의 의미를 깊이 이해하려면 복잡한 분석철학을 공부해야 할지 모른다. 최소한 다음은 기억하라. ‘쇼코의 미소’가 쇼코라는 여자의 미소가 아니라, 작가 최은영의 단편집 제목이라면 특수한 기호로 감싸야 한다. 고틀로프 프레게의 개념을 빌어 말하자면 일반적인 지시체가 아니기 때문이다. 더 깊이 생각하면 어느 지점부터 이런 구분조차 모호해진다. 그러니 너무 집착할 필요는 없지만, 원래 지시하던 것과는 다른 것을 지시할 때 특수한 기호로 감싼다는 것 정도는 알아두면 좋을 것 같다.

다양한 인용부호(‘’, “”, 『』, 「」, 《》 등)와 기울임 글꼴 등은, 모두 고틀로프 프레게의 지시체 개념과 관련이 있다.

띄어쓰기

조사만 붙여 쓰고 나머지는 띄어 쓰는 것이 원칙이지만 그리 간단하지 않다.

  1. 모든 낱말은 띄어 쓴다.
  2. 조사는 앞말에 붙여 쓴다.
  3. 의존 명사는 앞말과 띄어 쓴다.
  4. 단위를 나타내는 명사는 앞말과 띄어 쓰는 것을 원칙으로 하되 숫자와 어울리어 쓰일 때는 붙여 쓸 수 있다.
  5. 의미가 합쳐진 말은 붙여 쓴다.
  6. 단음절로 된 단어가 연이어 나타날 적에는 붙여 쓸 수 있다.
  7. 전문 용어, 성명 이외의 고유 명사는 붙여 쓸 수도 있다.
  8. 보조 용언은 띄어 씀을 원칙으로 하되, 때에 따라 붙여 쓸 수도 있다.
  9. 의미가 합쳐질 수 있는 말은 띄어 쓰는 것을 원칙으로 하되 붙여 쓰는 것을 허용한다.

따라서 아래는 모두 허용된다.

만성 골수성 백혈병
만성골수성백혈병
차 한 대가 지나간다.
차 한대가 지나간다.
두 시에 보자.
두시에 보자.
대한 중학교
대한중학교
도와드린다.
도와 드린다.

조사와 의존 명사도 자주 헷갈린다. ‘만큼’, ‘대로’, ‘뿐’, ‘만’ 등 많은 말들이 때에 따라 조사로 쓰이기도 하고 의존 명사로 쓰이기도 한다. 과거에는 ‘띄어 쓰기’가 맞았지만, 지금은 하나의 단어로 보아 ‘띄어쓰기’로 쓴다.

고유명사나 조어의 주체가 있는 단어는 권리자가 원하는 바를 존중한다.

(O) LG전자
(X) LG 전자
(O) 농구 선수 스테판 커리
(X) 농구 선수 스티븐 커리
(O) 영화감독 레오스 카락스
(X) 영화감독 레오 까라

정리하자면,

  • 조사는 붙여 쓰고 의존 명사는 띄어 쓰는 것에는 예외가 없으나 같은 말이 때에 따라 조사일 수도 의존 명사일 수도 있으니 유의해야 하고,
  • 보조 용언, 전문 용어, 고유 명사, 단위를 나타내는 명사는 의미가 합쳐질 수 있거나 단음절이 연이어 나타나거나 앞말과 어울리어 쓰일 때는 붙여 쓸 수도 있다.

의존명사, 보조 용언도 ‘낱말’이니 영어처럼 띄우고 싶고 ‘강남역사거리’가 ‘강남역사history거리’인지 ‘강남역네거리’인지 띄어쓰기로 구분하고 싶은 생각은 ‘한글 띄어쓰기’라는 괴물을 낳았다.

헷갈리지 않는 수준이면 조사는 물론 의존 명사, 보조 용언, 단위 등도 앞말과 붙여 쓰거나 반대로, 의미가 합쳐진 말이라도 띄어 쓰는 것이 합리적이라고 생각한다. 맞춤법을 복잡하게 만들어서 활용 상에서 발생하는 모호함을 해소하겠다는 발상은 지지하기 힘든다. 띄어 쓰는 것을 허용하되 붙여 쓰는 것을 원칙으로 하는 것이 우리말의 특징에 비추어 더 실용적이지 않을까?

현실에는, 띄어 쓰는 것을 원칙으로 하고, 합성어라는 명목으로 상식을 벗어난 수준의 예외를 계속 만들어 간다. 다음 예를 보자.

‘미친놈’은 합성어로 보지만, ‘미친’을 수식하거나 대상이 되는 명사가 오면 띄어 씁니다. 예) 그놈은 미친놈이다. 예) 등산에 아주 미친 놈이다.

표준국어대사전[국립국어원]은 ‘봄비’, ‘가을비’와 ‘겨울비’는 합성어로 봅니다. ‘여름비’는 합성어로 보지 않다가 개정되면서 합성어가 되었습니다.

‘올데갈데없다’는 표준국어대사전에 한 단어로 등재되어 있습니다. 만약 ‘올데갈데없다’외의 다른 형태면 띄어쓰기에 준해서 표기하셔야 합니다. 따라서 제시하신 ‘올데갈데도 없다’는 ‘올 데 갈 데도 없다’로 표기합니다.

‘해 질 녘’으로 띄어 쓰고 ‘저물녘’으로 붙여 씁니다. ‘저물녘’은 합성어로 사전에 올라 있는 말입니다.

‘grandmother’나 ‘online’을 합성어로 보고 붙여 쓰는 영어의 예와는 정도에서 심각한 차이가 있다. 그간 국립국어원이 일으킨 논란으로 분명한 것은, 그들이 대단히 흥미로운 집단이라는 점이다.

참고

괄호와 띄어쓰기

문장에서의 괄호는 보통 넣을 수도 뺄 수도 있는 글을 감싼다.

교착어가 아니라면, 앞말 뒤에 한 칸을 띄우고 괄호를 시작하면 문제가 생기지 않는다. 반면 우리말은 조사나 어미 앞에 괄호를 넣어야 하는 상황이 자주 발생하는데, 이때 한 칸 띄운다면 괄호 부분을 뺀 문장의 띄어쓰기가 어색하다. 그러니 앞말의 부연 용도로 괄호를 사용한다면 앞말에 붙여야 한다.

(X) 반도의 동부 (스칸디나비아 산맥의 동쪽)를
(X) 반도의 동부(스칸디나비아 산맥의 동쪽) 를
(X) 반도의 동부(스칸디나비아 산맥의 동쪽)을
(O) 반도의 동부(스칸디나비아 산맥의 동쪽)를

문장 끝에 있어도 마침표 앞에서 괄호를 여닫아야 한다. 마침표가 없는 앞말의 부연인 만큼 괄호 안에 마침표를 빼는 것이 자연스럽다.

(X) 영국에 갔다.(내가 제일 우려한 일이었다)
(X) 영국에 갔다 (내가 제일 우려한 일이었다).
(X) 영국에 갔다(내가 제일 우려한 일이었다.).
(O) 영국에 갔다(내가 제일 우려한 일이었다).

그러나 넣을 수도 있고 뺄 수도 있는 수식어를 괄호가 감싼다면 띄어 쓰는 것이 나을 것이다.

교착어란 (글자에 조사나 어미를) 아교(膠)로 붙인(着) 말(語)이라는 뜻입니다.

이 밖에도 제목으로 쓰일만한 단순한 명사형 표현은 한 칸 띄우고 괄호를 시작해도 어색하지 않은 경우가 많다.

(O) 영화 소개 (스포일러 주의!)
(O) 영화 소개(스포일러 주의!)
(O) 각종 행사(회갑, 결혼식, 돌잔치)를 지원합니다.
(X) 각종 행사 (회갑, 결혼식, 돌잔치)를 지원합니다.
(O) 각종 행사 지원 (회갑, 결혼식, 돌잔치)
(O) 각종 행사 지원(회갑, 결혼식, 돌잔치)
(O) C (학점)
(O) C (프로그래밍 언어)
(O) C(프로그래밍 언어)
(O) C (programming language)
(X) C(programming language)

마크다운

마크다운으로 글을 쓰는 사람이 많다. 먼저 Mastering Markdown을 숙지하라. Mastering Markdown에 나오는 개념(굵은 글꼴로 표시)을 중심으로 자주 하는 실수를 정리해 보았다.

  • 링크를 적절히 이용한다. 부연 설명보다 나을 때가 많다.
  • 제목은 헤더를 이용하며 #, ##, ### 등의 순으로 쓴다. 즉 ##으로 시작하거나 #에서 ###으로 건너뛰지 않는다.
  • #으로 시작하는 헤더대신 굵은 글꼴을 제목으로 사용하지 않는다.
  • 헤더만 뽑아서 읽어도 내적 논리를 발견할 수 있어야 한다. ‘의식의 흐름’대로 썼다면 논리를 발견하기 힘들 것이다. 좋은 문서를 찾아서 참고하라.
  • 코드 등은 신택스 하이라이트를 이용해서 표시한다.
  • 변수 등은 인라인 코드를 이용해서 표시한다.
  • 마침표가 나올 때마다 무분별하게 줄을 바꾸지 않는다. 단락 나누기 개념에 유의하라.
  • 리스트를 남용하지 않는다. 온전한 문장들로 구성된 단락을 선호하라. 열거할 대상을 규정하는 문장이나 제목이 선행할 때만 제한적으로 리스트를 사용한다.

일본어의 잔재

온갖 부적절한 단어, 나쁜 글쓰기 습관을 일본어의 잔재로 몰아붙이는 사람들이 있다. 그러나 ‘과학’, ‘이성’ 등 서양의 개념에 대응되는 말은 대부분 한국어도 중국어도 아닌 일본어라는 사실을 인정할 필요가 있다.

‘나무들이 많다’라는 말보다 ‘나무가 많다’라는 말이 한국어로 더 자연스럽다. 대부분의 문화권에서 피동태는 좋지 않다고 말한다. 이처럼 한국어 특수성을 무시한 표현이나 대부분의 문화권에서 나쁘다고 합의된 표현은 피하되, ‘일본어의 잔재’라는 허상에 얽매이지 않았으면 한다. ‘과학’ 대신 ‘격물치지’를, ‘이성’과 ‘감정’ 대신 ‘사단칠정’을 쓰고 싶지 않다면 말이다.

개념 체계가 고도화된 언어에서 피동태가 남용되는 경향이 있다. 피동태가 드물고 개념 분화가 덜 된 언어가 순수하다는 생각은 망상에 가깝다.

@vieryuke
Copy link

기술 문서를 작성할 때 라도 의미가 잘못 전달되지 않도록 하려고
문법이나 표현 어휘를 가능하면 표준에 따르려고 노력 하는데
작성하신 글에 많은 도움과 생각을 얻었습니다.
감사합니다.

@9beach
Copy link
Author

9beach commented Sep 1, 2018

도움이 되셨다니 기쁩니다.

@juunone
Copy link

juunone commented Sep 7, 2020

기술문서 작성하는데 참고 많이됐습니다
특히 '명징한 소재' 는 항상 의식해서 실천하려고 하고있네요
좋은 글 감사합니다.

@spriteye
Copy link

계속 업데이트가 되고 있었군요! 항상 잘 참고하고 있습니다. 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment