Skip to content

Instantly share code, notes, and snippets.

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

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

텍스트 파일의 장점

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

명징한 소재

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

단락 나누기

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

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

도입부

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

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

배경, 목적, 범위

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

글을 이루는 요소를 Why, What, How 등의 요소로 보았을 때 많은 사람이 자신이 천착하는 소재에 함몰되어, 즉 자신이 이 글을 왜 쓰는가에 대해서는 남들도 알고 있다고 착각하여, 거두절미하고 How에 관해서만 기술하는 경향이 있다. 성인답지 못한 행동이다.

보편적인 소재에 대한 전략

보편적인 소재의 글에 대한 글은 전략이 뚜렷해야 한다.

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

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

제목의 변별력

준비물과 같은 이름의 페이지를 만드는 것보다는 연신내 청소년 캠프 준비물이 나을 것이다. 물론 위키 시스템이 폴더나 네임스페이스를 지원한다면 그것을 적절히 활용하는 것도 일리가 있지만 그것과 무관하게 제목이 변별력을 가지는 것은 중요하다.

제목의 어법

(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 서비스 실태 연구
(X) 연구과제: 한국의 웹2.0 서비스 실태
(O) 한국의 웹 2.0 서비스

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

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

중복

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

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

위의 예 중 한국의 웹 2.0 서비스 소개는 발표자료라면 소개를 빼는 것이 합당하지만 그렇지 않은 상황이라면 허용되는 상황도 있을 것 같다.

제목과 상위의 범주

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

위의 관리자는 사용자를 추가할 수 있어야 한다.는 요구사항에 어울리는 표현이지 기능 명세에 어울리는 표현이 아니다. 그러니 should, may 등의 의미를 뺀 관리자에의한 사용자 추가라는 제목이 더 나을 것 같다.

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

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

맞춤법

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

띄어쓰기

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

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

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

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

조사와 의존 명사도 자주 헷갈린다. 만큼, 대로, , 등 많은 말들이 경우에 따라 조사로 쓰이기도 하고 의존 명사로 쓰이기도 한다. 띄어쓰기도 원래 띄어 쓰기가 맞지만 이미 하나의 단어가 되어서 띄어쓰기가 맞다.

고유명사 혹은 조어의 주체가 있는 단어에 대해, 규칙이 아니라 소유자가 원하는 바를 존중해야할 경우도 있다.

(O) LG전자
(X) LG 전자

정리하자면,

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

추측컨데, 교착어라는 특수성에 더해 충분한 어휘를 가지지 못한 채 다른 나라 언어의 발음기호처럼 쓰는 한글이 가진 모호함을 띄어쓰기로 해소하고 싶은 생각에서 이런 규칙을 만들지 않았을까 하는 생각이 든다. 의존명사도 낱말이니 영어처럼 띄우고 싶고, 강남역사거리강남역사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)

외국어와 한글의 혼용

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

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

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

널리 통용되지는 않지만, 문장 중간에서 표기언어가 바뀔 때에는 묵시적으로 구분자가 들어가는 것이나 마찬가지이니 괄호를 사용하지 않는 것도 일리가 있다.

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

일본어의 잔재

온갖 부적절한 단어, 나쁜 글쓰기습관을 일본어의 잔재로 몰아붙이는 사람들이 있다.

위에서 사용한 '명사'도 일본어일지 모른다. 확실한 것은 '과학', '이성' 등 서양의 개념에 대응되는 말은 대부분 한국어도 중국어도 아닌 일본어라는 사실이다.

한국어에는 원래 사물에 대한 복수형이 없으니 '나무들'이라는 말은 잘못된 표현이다. 피동태를 쓰는 것은 언어를 떠나서 대부분의 문화권에서 좋지않다고 말한다. 결론만 말하자면 한국어의 특수성을 무시한 표현이나 대부분의 문화권에서 나쁘다고 합의된 표현은 피하되, '왜말의 잔재'라는 허상에 얽메이지 않기를 권한다. '과학'대신 '격물치지'를, '이성'과 '감정'대신 '사단칠정'을 쓰고 싶지 않다면 말이다.

개념체계가 발달한 언어체계에서 피동태가 남용되는 경향이 있다. 피동태가 없는 것에 "순수함"이라는 망상을 과도하게 투여해서 불필요하게 싸우지 말자.

@gayakps
Copy link

gayakps commented Mar 10, 2022

잘 읽었습니다

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