Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
기술 문서를 쓸 때 주의해야 할 몇 가지를 나열합니다.

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

텍스트 파일의 장점

자기 일이 소모적인 일회성 일이 아니라고 여긴다면 위키에 글을 작성하고 공유하라. 토론은 해당 페이지에서 이루어지는 것이 좋다. 중요한 정보를 위키나 깃Git으로 관리되는 텍스트가 아닌, 워드나 파워포인트와 같은 이진 문서로 작성할 때마다 당신의 동료는 접근성, 가시성, 버전 관리 등 다양한 문제로 고통을 겪을 것이다.

명징한 소재

잡다한 소재가 하나의 글에 다 들어가 있으면 다듬기도, 다른 곳에 활용하기도 힘들다. 자기 완결적인 여러 개의 글로 나눔으로써 정보로서의 가치가 더 커진다. 나중에 나눌 의향으로 일단 쓰고 보는 것은 환영한다. 고민하면서 글쓰기를 미루는 것보다는 일단 쓰는 것이 중요하다.

단락 나누기

글의 내용을 지나치게 개념화하여 명사형으로 나열하는 것은 말로 설명이 덧붙는 브리핑에서나 유용하다. 위키에 오른 글은 일차 자료로써, 간명하되 충분한 정의나 설명을 포함해서 내러티브를 갖추고 자기 완결적이어야 한다.

간략히 쓰되 단락을 적절하게 나누라. 이유 없이 명사형으로 간추려서 의미를 모호하게 만들지 말라. 들여 쓸 정도로 글을 계층화하는 습관은 많은 단점을 가진다. 생각이 충분히 정리되지 않았다는 것을 뜻하기도 한다. 제목과 내용, 이 둘의 반복으로 단순하게 구성하되, 긴 내용은 단락을 나누어서 깨끗하게 정리하라.

도입부

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

반드시 두괄식으로 써야만 하는 것은 아니지만, 도입부를 정의로 시작하는 것은 괜찮은 방식이다.

배경, 목적, 범위

배경, 목적, 범위 등의 설명을 생략한 채 곧장 하고 싶은 말이나 합의된 결과만 나열한다면, 그 글은 타인에게 공유하기에는 부적당한 회의록이나 상념 수준의 글이 될 것이다. 배경, 목적, 범위를 간략하게 기술하려는 노력이 필요하다.

많은 사람이 자신이 천착하는 소재에 함몰되어, 즉 자신이 이 글을 왜 쓰는지를 남들도 알고 있다고 착각하여, 거두절미하고 결론만 기술하는 경향이 있다. 미성숙한 태도이다.

외국문자와 한글의 혼용

결론부터 말하면, 외국문자와 한글을 섞어 적는 것은 존중할 만한 교열 정책에서는 존재하지 않는다. 즉 ‘합의했다’ 대신 ‘컨센서스를 이루었다’고 쓰는 것은 권하기는 힘들지만 틀린 것은 아니다. 그러나 ‘Consensus를 이루었다’라고 쓴다면 이는 틀린 것이다.

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

원어 표기보다는 한글 위키피디아 등을 참고해서 한글로 쓰는 것을 권한다. ‘IBM’ 수준의 단어가 아닌 경우에는 ‘클라우드 컴퓨팅’, ‘아파치 하둡’, ‘엘지전자’ 등과 같이 한글로 표기하는 것이 올바르다.

모든 나라말을 모조리 한글로 표기하는 것은 의외로 상식적이고 온건한 방식이다. 영어권 국가에서 ‘브라질’을 ‘Brazil’로 적고 ‘브라지으’로 발음하지만, 브라질에서는 ‘Brasil’로 적고 ‘브라지우’로 발음한다. 한국에서는 ‘브라질’ 또는 ‘Brazil’로 쓰고 있다. 원어로 쓰려면 ‘Brasil’로 써야 할 것이고 해당 국가 발음에 맞게 한글로 쓰려면 ‘브라지우’로 써야 할 것이다. 하지만 현실은 영어권 국가가 쓰는 표기나 발음을 따르는 경우가 많다. 한글로 표기한다고 해서 이런 문제를 모두 해결할 수는 없지만, 외래어 표기법에 따라 모두 한글로 표기하는 것은 적어도 영어로 표기하는 것보다는 나은 선택이며, 공적으로 합의되고 검증된 방식이다.

외국문자를 쓸 때 예외 없이 한글과 함께 적기로 한 이상, 문장 중간에서 표기 언어가 바뀔 때는 묵시적으로 구분자가 들어가는 셈이라 괄호를 사용하지 않는 것도 일리가 있다. 많이 사용되는 표기법이기도 하다.

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

보편적인 소재의 글

보편적인 소재의 글을 쓸 때는 전략이 뚜렷해야 한다.

기술 문서로서 의미 있는 글의 표제는 백과사전이나 국어사전의 그것에 비교해 다소간의 구체성을 가질 것이다. 하지만 피치 못할 이유에서 ‘논리’, ‘언어’ 등과 같이 백과사전에나 어울릴만한 제목으로 글을 쓸 때는 그에 걸맞은 전략이 필요하다. 위키피디아의 내용을 알기 쉽게 간추려서 적거나 단순한 번역문을 올리거나 하는 식의 글쓰기는 피해야 한다. 전략을 뚜렷하게 정해야만 무의미하거나 혹은 반대로 편벽한 글로 남지 않을 것이다.

글을 쓰기 전에 구체적인 술어나 한정사를 두어서 전략에 맞게 제목을 구체화하려고 노력해야 한다. 특별한 목표나 시각, 전략이 없다면 굳이 새로 쓰지 않고, 한글이든 영문이든 위키피디아의 해당 페이지로 링크하는 것도 고려하라.

제목의 변별력

‘준비물’과 같은 이름의 페이지를 만드는 것보다는 ‘2018년 용산 청소년 캠프 참가자 준비물’이 나을 것이다.

제목의 어법

(X) Tip: Installing Samba
(O) Installing Samba Tip
(X) HOWTO: Installing Apache
(O) How To Install Apache
(O) C (programming language)
(X) 연구과제: 한국의 웹2.0 서비스 실태
(O) 한국의 웹 2.0 서비스 실태 연구
(O) 한국의 웹 2.0 서비스

글 제목을 지을 때 자신만의 특이한 체계가 특별하게 허용되는 것은 아니다. 보편적인 어법에 맞추도록 노력하라.

이렇게 어법을 깨는 데는 다양한 이유가 있겠으나 종류, 위상 등의 동의받지 않은 메타 정보를 제목에 넣고 싶은 욕구도 큰 부분을 차지한다고 추측한다. 위키에서 하나의 글은 전체 위키 공간의 일부이다. 위키 글 하나는 관계(링크) 속에서 다양하게 위치하며 규정된다. 작성 당시 자신만의 특수한 맥락으로 글을 속박하는 것은 좋지 않다. 동의받지 않은 자신의 체계를 타인에게 노출하는 미성숙한 행위로 비난받을 수 있다.

중복

의미가 작거나 중복인 말은 제거하는 것이 좋다.

(X) 아파치 서버 설치법
(O) 아파치 서버 설치
(X) 한국의 웹 2.0 서비스 소개
(X) 만족해야 할 니즈
(O) 필요성
(X) 아주 큰 비중을 차지한다.
(O) 큰 비중을 차지한다.
(X) 꼭 필요한

상위 범주와 제목

    # 소프트웨어 기능 명세
(X) ## 관리자는 사용자를 추가할 수 있어야 한다.
(O) ## 관리자에 의한 사용자 추가

‘관리자는 사용자를 추가할 수 있어야 한다.’라는 문장는 요구사항에나 어울리지 기능 명세에 어울리지 않는다. 그러니 ‘관리자에의한 사용자 추가’라는 문장이 이 더 나을 것 같다.

    # 주요 기능
(X) ## 관리자 추가 기능
(O) ## 관리자 추가

기능을 나열하는 범주 아래에 있는 만큼 모든 제목의 끝에 ‘기능’이라는 말을 다 넣을 필요는 없을 것같다.

맞춤법

자동 맞춤법 검사기를 활용하라.

인용부호

큰따옴표와 작은따옴표의 용도는 모두 잘 알고 있을 것이다. 인용한다는 것의 의미를 논리적으로 엄밀하게 생각하다 보면 복잡한 현대 논리학을 공부해야 할지도 모른다. 최소한 다음은 기억할 필요가 있다. “쇼코의 미소”가 쇼코라는 여자의 미소를 뜻하려는 것이 아니라 작가 최은영의 단편집 “쇼코의 미소”를 뜻하는 것이라면 인용부호로 감싸야한다. 고틀로프 프레게Gottlob Frege의 개념을 빌어서 말하자면 의미sense가 아니라 지시체reference이기 때문이다. 깊이 생각하면 어느 지점에서는 의미와 지시체의 구분조차 모호해진다. 일상 언어란 그런 것이다. 그러니 너무 집착할 필요는 없지만, 대화 이외에도 특수한 기호로 감싸야 할 대상이 있으며 그것은 주로 단어가 일차적인 의미로 사용될 때가 아니라 다른 것을 지시할 때라는 것을 알고 있다면 좋을 것 같다.

권위 있는 출판사의 교열 정책은 다양한 인용부호(‘’, “”, 『』, 「」, 《》 등)와 기울임 글꼴의 사용을 포함하지만, 이것들이 감싸는 것은 여전히 지시체라는 개념 아래에 둘 수 있다.

띄어쓰기

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

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

따라서 아래는 모두 허용되는 표기이다.

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

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

고유명사 혹은 조어의 주체가 있는 단어 등 소유자가 원하는 바를 존중해야 할 때도 있다.

(O) LG전자
(X) LG 전자
(O) 농구 선수 스테판 커리
(X) 농구 선수 스티븐 커리

정리하자면,

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

추측 건데, 교착어라는 특수성에 더해 충분한 어휘를 가지지 못한 채 다른 나라 언어의 발음기호처럼 쓰는 한글이 가진 모호함을 띄어쓰기로 해소하고 싶은 생각에서 이런 규칙을 만들지 않았을까. 의존명사도 낱말이니 영어처럼 띄우고 싶고, ‘강남역사거리’가 ‘강남역사history거리’인지 ‘강남역네거리’인지도 띄어쓰기로 구분하고 싶은 그런 생각 말이다.

헷갈리지 않는 수준이면 조사는 물론 의존 명사, 보조 용언, 단위 등도 앞말과 붙여 쓰거나, 아니면 그 반대로 의미가 합쳐진 말이라도 예외 없이 띄어 쓰는 식으로 한글 맞춤법이 바뀌었으면 좋겠다. 활용 상에서 발생할 수 있는 모호함을 맞춤법을 복잡하게 만들어서 해소하겠다는 발상도 이상하지만, 설령 그런 발상을 인정한다고 해도 붙여 쓰는 것을 원칙으로 하고 띄어 쓰는 것을 허용하는 것이 우리말의 특징에 비추어 더 실용적이지 않을까?

참고

괄호와 띄어쓰기

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

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

(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에 나오는 개념(굵은 글꼴로 표시)을 중심으로 자주 하는 실수를 정리해 보았다.

  • 제목은 헤더를 이용하며 #, ##, ### 등의 순으로 쓴다. 즉 ##으로 시작하거나 #에서 ###으로 건너뛰지 않는다.
  • 헤더가 아닌 패러그래프는 설령 굵은 글꼴이라고 해도 제목으로 사용하지는 않는다.
  • 마침표를 포함한 온전한 문장은 제목으로 사용하지 않는다.
  • 코드 등은 신택스 하일라이트 기능을 이용해서 표시한다.
  • 변수 이름 등은 인라인 코드를 이용해서 표시한다.
  • 마침표가 나올 때마다 무분별하게 줄을 바꾸지 않는다. 단락 나누기 개념에 유의하라.
  • 리스트를 남용하지 않는다. 온전한 문장들로 구성된 단락을 선호하라. 리스트를 사용할 때는 그 앞에, 열거될 대상을 규정하는 온전한 문장 또는 제목이 선행해야 한다.

일본어의 잔재

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

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

개념 체계가 고도화된 언어에서 피동태가 남용되는 경향이 있다. 피동태가 드물고 개념 분화가 덜 된 초보적인 언어에 ‘순수함’이라는 망상을 과도하게 투여할 필요는 없어 보인다.

@Sangdol

This comment has been minimized.

Copy link

commented May 21, 2017

여러가지 고민하던 부분이 잘 정리되어 있어서 큰 도움 얻고 갑니다.

@wakeup5

This comment has been minimized.

Copy link

commented Sep 25, 2017

좋은 정보 감사합니다.

@x90chacker

This comment has been minimized.

Copy link

commented May 11, 2018

좋은 글이네요.

@vieryuke

This comment has been minimized.

Copy link

commented Jul 18, 2018

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

@9beach

This comment has been minimized.

Copy link
Owner Author

commented Sep 1, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.