Skip to content

Instantly share code, notes, and snippets.

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

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

텍스트 파일의 장점

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

명징한 소재

잡다한 소재가 하나의 글에 다 들어가 있으면 재활용성, 접근성, 발전 가능성이 떨어진다. 자기 완결적인 항목들로 페이지를 나눔으로써 정보로서의 가치가 더 커진다. 나중에 나눌 의향으로 일단 쓰고 보는 것은 환영한다. 고민하면서 글쓰기를 미루는 것보다는 일단 쓰는 것이 중요하다.

단락 나누기

간략하게 항목화하여 나열하는 것은 말로 하는 설명이 덧붙는 브리핑에서나 유용하다. 위키에 오른 글은 일차 자료로써, 간명하되 충분한 정의 혹은 설명을 포함해서 자기 완결적이어야 한다.

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

도입부

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

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

배경, 목적, 범위

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

글을 이루는 요소를 ‘왜why’, ‘무엇을what’, ‘어떻게how’로 보았을 때 많은 사람이 자신이 천착하는 소재에 함몰되어, 즉 자신이 이 글을 왜 쓰는가에 대해서는 남들도 알고 있다고 착각하여, 거두절미하고 ‘어떻게how’에 관해서만 기술하는 경향이 있다. 미성숙한 태도이다.

외국문자와 한글의 혼용

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

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

원어 표기보다는 한글 위키피디아 등을 참고해서 한글로 쓰는 것을 권한다. 위의 예에서는 ‘런던에서’, ‘도쿄에서’가 제일 나은 것 같다. 그러니 ‘IBM’ 수준의 단어가 아닌 경우에는 ‘클라우드 컴퓨팅’, ‘아파치 하둡’, ‘엘지전자’ 등과 같이 한글로 표기하자.

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

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

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

보편적인 소재에 관한 전략

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

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

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

제목의 변별력

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

제목의 어법

(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이기 때문이다. 깊이 생각하면 어느 지점에서는 의미와 지시체의 구분조차 모호해진다. 일상 언어란 그런 것이다. 그러니 너무 집착할 필요는 없지만, 대화 이외에도 특수한 기호로 감싸야할 대상이 있으며 그것은 주로 단어가 일차적인 의미로 사용될 때가 아니라 다른 것을 지시할 때라는 것을 알고 있다면 좋을 것 같다.

권위 있는 출판사의 교열정책은 다양한 인용부호(‘’, “”, 『』, 「」)와 기울임 글꼴의 사용을 포함하지만, 이것들이 감싸는 것은 여전히 지시체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)

일본어의 잔재

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

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

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

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