테크니컬 라이팅이란? - IT인을 위한 글쓰기 가이드

오늘은 네이버, NHN에서 테크니컬 라이터로 일하셨던 유영경 저자의 <개발자를 위한 글쓰기 가이드>를 참고하여 글쓰기 가이드를 정리해보았습니다.

IT 업계 종사자라면 직무를 막론하고 제품이나 기술에 대한 글을 써야하는 일이 많을텐데, 더 쉽게 잘 읽히는 글을 쓰는 데 이 요약글이 조금이나마 도움이 되면 좋겠습니다.🙏 

---

Photo by Ilya Pavlov on Unsplash

 

테크니컬 라이팅이란? 

 Q. 테크니컬 라이팅이란? 
  - 기술/과학 분야에서 정보를 정확하게 전달하기 위한 글쓰기를 뜻합니다. 

 Q. 테크니컬 라이터는 뭐하는 사람일까? 
  - IT분야에서 기술 문서를 개발하는 사람들을 말합니다. 
  - 제품, 서비스, 장비 등을 사용자가 쉽게 사용하거나 운영할 수 있게 정확한 정보를 전달하는 일을 합니다. 
  - 복잡하고 어려운 기술/정보를 대상 독자 눈높이에 맞게 설명해야하며, 때에 따라 일러스트를 작성하거나 동영상 가이드를 만들기도 합니다. 

 Q. 기술 문서는 어떤게 있을까?
  - 컴퓨터 애플리케이션, 의료 절차과 같이 전문적 내용을 다루는 문서, 제품 설명서, 가이드, 도움말, 백서 등
  - 넓게 보면 메일, 보고서, 회의록, 보도 자료 등도 포함됩니다. 

 Q. 테크니컬 라이팅은 일반 글쓰기와 뭐가 다를까? 
  - 객관적인 사실에 기반한 내용을 다룹니다.
  - 직설적이고 보편적인 표현을 사용합니다.
  - 내용이 작업 순서에 따른 순차적 흐름으로 구성됩니다. 
  - 특정한 타겟 독자가 존재합니다. (개발자, 엔지니어, 특정 서비스를 사용하는 유저 등)

  

 

테크니컬 라이팅의 5단계

 1. 계획 세우기: 기술 문서의 목적과 대상 독자 설정합니다. 
 2. 구조 잡기: 계획 단계에서 수집한 정보를 구조화하여 글의 순서와 배열을 잡습니다. 
 3. 초안 작성하기: 전달할 내용을 모두 넣는 것에 초점을 맞춰 일단 씁니다. (문법, 맞춤법 신경 X)
 4. 검토/재작성하기(=리라이팅): 내용, 문서 구조, 문장 연결, 문법, 맞춤법 등 모든 항목들을 검토하여 최종본을 만듭니다. 
    👉 전체 문서 작성 시간의 40% 정도 가장 많은 시간 할애하는 과정입니다. 
 5. 문서 배포: 완성된 문서를 독자들에게 배포합니다. (메일, PDF, 웹 페이지 등의 형식 활용)
    👉 배포 후 서비스의 기능 변경 사항을 정기적으로 반영하는 업데이트 과정도 필요합니다. 

 

 

테크니컬 라이팅의 3 원칙 - 명확성, 간결성, 일관성 

1. 명확성: 정확한 정보를 기반으로 단호하고 명확한 설명과 표현을 사용합니다.
2. 간결성: 전달하려는 바가 빠르게 이해될 수 있도록 문장을 짧고 쉽게 구성합니다. 
3. 일관성: 문서 전체에서 설명하는 내용, 용어, 설명 방법 등이 일관되게 작성합니다. 

 

1. 명확성을 높이는 글쓰기 방법

먼저 핵심부터 쓰세요.

- 핵심 내용부터 작성 후 내용을 뒷받침하는 근거나 설명을 덧붙입니다.
- 중요한 내용부터 덜 중요한 내용 순서로 작성하는 역피라미드 방식을 이용합니다.
- 문서의 제목에 요점을 담습니다. 제목을 작성할 때 다음을 고려합니다. 

✅  제목 작성 체크리스트

(1) 내용이 무엇인 지 한 눈에 알 수 있는가?

(2) 부제목이 필요하지 않은가?

(3) 목적과 방법을 명확하게 알 수 있는가?

(4) 명사만 나열하지 않고 의미를 정확하게 서술했는가?

(5) 널리 알려지지 않거나 표준이 아닌 약어를 사용하진 않았는가?

 

단정적 어조로 확신있게 쓰세요. 

[예시] 글꼬리 뚜렷하게 쓰기 
열기를 클릭하면 새 창이 열리게 됩니다. (X) ➡️ 열기를 클릭하면 새 창이 열립니다. (O) 
'결제 복구 기능'을 사용하면 좋을 듯합니다. (X) ➡️ '결제 복구 기능'을 사용합니다. (O)
방법은 크게 세 가지로 볼 수 있다. (X) ➡️ 방법은 크게 세 가지다. (O)

 

번역체에서 벗어나세요.

[예시] 피동태/이중피동태 수정 
파이썬은 귀도 반 로섬에 의해 개발되었습니다 (X) ➡️ 파이썬은 귀도 반 로섬이 개발했습니다 (O)
결과 로그가 화면에 보여집니다 (X) ➡️ 결과 로그가 화면에 나타납니다 (O)
화면 오른쪽 상단에 보여지는 확인 버튼을 클릭합니다. (X)  ➡️ 화면 오른쪽 위의 확인 버튼을 클릭합니다. (O)

[예시] "~에 대해/의해/통해" 수정
자바 스크립트 성능에 대해 알아보자 (X) ➡️ 자바 스크립트 성능을 알아보자(O)
성능을 향상시키는 것은 코드를 다듬는 것에 의해 이뤄질 수 있다. (X) ➡️ 코드를 다듬어 성능을 향상할 수 있다. (O)
성능 향상은 다음 세가지 방법을 통해 가능하다. (X) ➡️ 성능 향상 방법은 다음 세가지이다. (O)
빌드 버튼을 통해 빌드를 생성한다 (X) ➡️ 빌드 버튼을 클릭해 빌드를 생성한다. (O)

[예시] "가능/불가능하다, ~를 가지고 있다" 수정 
(X) 성능 향상은 다음 3가지 방법으로 가능하다 ➡️
(O) 다음 3가지 방법으로 성능을 향상할 수 있다/성능 향상 방법은 다음 3가지이다
모바일 기기들은 기종별로 다양한 해상도를 가지고 있다 (X) ➡️ 모바일 기기의 해상도는 기종별로 다르다 (O)

[예시] "무엇은 ~ 무엇이다." 수정
이 책은 기술 문서를 쓰는 사람에게 도움이 되는 책이다 (X) ➡️ 이 책은 기술 문서를 쓰는 사람에게 도움이 된다 (O)
새로 나온 협업 서비스인 'A 메신저'를 알아보자. 'A 메신저'를 사용하면 편리하게 업무를 관리할 수 있다 (X)
➡️ 새로 나온 'A 메신저'는 편리하게 업무를 관리할 수 있는 협업 서비스다. (O)

[예시] "~해주다/해놓다" 수정 
다음과 같이 구현해 주어야 합니다 (X) ➡️ 다음과 같이 구현해야 합니다 (O)
홈 화면에 추가해 놓아 두고 사용하시면 편리합니다 (X) ➡️ 홈 화면에 추가해 사용하면 편리합니다 (O)

[예시] 군더더기 표현 덜어내기 
인증서 도메인 당 월 8만 원의 비용이 발생합니다 (X) ➡️ 인증서 비용은 도메인 당 월 8만 원입니다  (O) 
서비스를 활성화하려면 콘솔 로그인이 필요합니다 (X) ➡️ 서비스를 활성화하려면 콘솔에 로그인해야 합니다 (O) 
버튼을 눌러 다운로드를 진행해 주세요 (X) ➡️ 버튼을 눌러 다운로드해 주세요  (O) 

 

은어는 형식적인 표현으로 바꾸세요. 

[예시] 은어 수정 
대화 상자가 뜨면 메일 주소를 입력합니다 (X) ➡️ 대화 상자가 나타나면 메일 주소를 입력합니다 (O)
한글이 깨져 보일 수 있습니다 (X) ➡️ 한글이 제대로 보이지 않을 수 있습니다 (O)

 

용어는 정확하게 쓰세요. 

[예시] 대명사는 일반 명사로 바꾸기
더 많은 사용법을 보려면 여기를 참고하시기 바랍니다 (X) ➡️ 더 많은 사용법은 API 레퍼런스를 참고하시기 바랍니다(O)
캘린더를 사용하면 동료와 쉽게 일정을 공유할 수 있습니다. 이를 통해 프로젝트 진척도 관리 할 수 있습니다 (X)
➡️ 캘린더를 사용하면 동료와 쉽게 일정을 공유할 수 있습니다. 캘린더에서 프로젝트 진척도 관리 할 수 있습니다(O)

[예시] 고유 명사를 줄여쓰거나 한글로 바꿔 쓰지 않기 
MS (X) ➡️ Microsoft (O)
Win10 (X) ➡️ Windows 10(O)
AOS (X) ➡️ Android (O)
IE (X) ➡️ Internet Explorer (O)
구글 (X) ➡️ Google (O)
아이폰 (X) ➡️ iPhone (O)

 

 

2. 간결성을 높이는 글쓰기 방법

무조건 쉽게 쓰세요. 

[예시] 독자가 이해하기 어려운 전문 용어는 피하기 (독자 수준 고려하여 결정)
기술 문의 엔트리 포인트는 클라이언트팀 소속입니다 (X) ➡️ 기술 문의 담당자는 클라이언트팀 소속입니다 (O)
GNB 메뉴 우측의 회원가입을 클릭합니다 (X) ➡️ 화면 오른쪽 위의 회원 가입을 클릭합니다 (O) 

[예시] 용어 풀어쓰기
(X) 스니퍼는 스니핑을 할 수 있는 도구이다  ➡️
(O)스니핑(snifing)은 해킹 기법의 하나로, 네트워크에서 상대방의 패킷 교환을 엿듣는 것을 의미한다. 이렇게 스니핑을 할 수 있는 도구를 스니퍼(sniffer)라 한다 (O) 

[예시] 약어 풀어쓰기
(X) IAP 의존도가 높아지고 있다  ➡️
(O) 인앱 구매(IAP, in-app purchase)는 일부 앱 안에서 추가 콘텐츠나 서비스를 유료로 결제하는 것을 뜻한다. 최근 인앱 구매의 의존도가 높아지고 있다. 

 

문장을 짧게 줄여쓰세요. 

[예시] "을/를", "의" 등 조사 덜어내기  
시스템 사용을 하기 전에 환경부터 설정을 해야 합니다 (X) ➡️ 시스템을 사용하기 전에 환경부터 설정해야 합니다 (O) 
클라우드 서비스로의 이전 (X) ➡️ 클라우드 서비스로 이전 (O) 
환경 설정의 편리함 (X) ➡️ 편리한 환경 설정 (O) 

[예시] 의미가 같은 표현은 1번만 쓰기
과반 수 이상이 (X) ➡️ 과반 수가 or 절반 이상이 (O) 
기존에 이미 (X)  ➡️ 기존에 or 이미 (O)
하게 되면 (X)  ➡️ 하려면 (O)

 

시각화 자료로 가독성을 높이세요. 

  - 표, 그림, 스크린숏, 차트 등 적합한 시각 자료를 활용하세요.
  - 시각 자료가 문서 전체에 5개 이상이면  캡션을 넣으세요. 
   👉 캡션의 위치: 그림 캡션은 그림 왼쪽 아래, 표 캡션은 표 나오기 전 왼쪽 위에!
         ex) "그림 1. 메일 환경 설정", "그림 2. 메일 글꼴 설정"

  - 번호 목록과 점 목록을 사용해 나열하세요.

[예시] 번호 목록: 순서가 중요할 때
(X) Firebase에서 API 키를 생성하면 먼저 Firebase 콘솔에 접속해야 합니다. CREATE NEW PROJECT를 클릭하고 프로젝트 이름과 정보를 입력합니다. ➡️
(O) Firebase에서 API 키를 생성하는 방법은 다음과 같습니다.
 1. Google Firebase 콘솔에 접속합니다.
 2. CREATE NEW PROJECT를 클릭합니다.
 3. 프로젝트 이름과 정보를 입력합니다.
...

[예시] 점 목록: 각 항목이 대등하고 순서 상관없이 나열할 때 
(X) 많은 기업에서 K 클라우드를 도입하는 이유는 총 3가지로, 비용을 절감할 수 있고 속도를 높일 수 있으며, 원하는 만큼 리소스를 사용할 수 있기 때문입니다. ➡️
(O) K 클라우드를 도입하는 주요 이유 3가지는 다음과 같습니다. 
 ∙ 비용 절감 
 ∙ 빠른 속도
 ∙ 뛰어난 리소스 확장성     

 

 

3. 일관성을 높이는 글쓰기 방법 

용어와 표현을 일관되게 사용하세요. 

[예시] 용어와 표현 일관되게 사용하기  
스토리지/저장소 (X) ➡️ 이 중 하나로 일관되게 작성 (O) 
보안 그룹/시큐리티 그룹 (X) ➡️ 보안 그룹으로 일관되게 작성 (O) 
화면에서 앱을 선택합니다/누릅니다/터치합니다(X) ➡️ 이 중 하나로 일관되게 작성 (O) 
화면/스크린 (X) ➡️ 이 중 하나로 일관되게 작성 (O) 

 

목록과 시각 자료를 사용할 때 일관성을 유지하세요.

- 목록을 사용할 때는 각 항목의 문법적 일관성을 유지합니다.  

[예시] 점 목록 항목 일관성 유지하기
∙ 사과  ∙ 딸기  ∙ 배입니다 (X) ➡️ ∙ 사과  ∙ 딸기  ∙ 배 (O) 

- 이미지를 캡처할 때는 프로그램/운영체제의 환경을 통일하고 그림 크기를 일관되게 지정합니다. 

 

문장부호 작성 규칙을 따르세요.

- 마침표(.): 문장을 마칠 때, 날짜를 표현할 때, 하위 장이나 절을 나타낼 때 사용합니다.

[예시] 마침표
2020. 12. 26 (X) ➡️ 2020.12. 26. (O) 

- 쌍점(: ): 시와 분이나 분과 초를 구분할 때, 대(vs), 부제목에 사용합니다. 

[예시] 쌍점은 앞말에 붙여 쓰고 뒷말과는 뛰어 쓰기
개발자를 위한 테크니컬 가이드: 50가지 팁

- 큰 따옴표(" "): 낱말이나 문장을 직접 인용할 때, 책 제목을 나타낼 때 사용합니다.

[예시] 큰 따옴표
배달 앱 기획자는 "앱을 직관적으로 사용하게 하는 것이 목표였다"라고 말했다.
2021년 출간된 "테크니컬 라이팅 가이드"는 개발자를 위한 책이다. 

- 작은 따옴표(' '): 문장의 중요한 부분을 강조할 때, 인용한 말 안에서 인용할 때, 소제목을 나타낼 때 사용합니다.

[예시] 작은 따옴표
데이터를 서로 비교할 때는 '표'를 사용하면 좋습니다.
"시각 자료를 활용하면 이해도가 높아집니다. '백문이 불여일견'이라는 말도 있듯이 말입니다."
문장부호 사용법은 '문장부호 바로 쓰기' 절을 참고하시기 바랍니다. 

- 소괄호 ( ): 보충설명 덧붙일 때, 우리말 표기와 원어 표기를 같이 쓸 때, 생략할 수 있는 내용을 나타낼 때 사용합니다.

[예시] 소괄호
이 책은 테크니컬 라이팅(기술 글쓰기) 방법을 다룬다.
스미싱(smishing)은 문자 메시지를 사용한 피싱 방법이다.
변수 뒤에 조사를 쓸 때는 '을(를)', '이(가)'와 같이 씁니다. 

 

---

출처: 유영경, <개발자를 위한 글쓰기 가이드 >, 로드북 (2021)