테크니컬 라이팅(Technical Writing)의 정의
테크니컬 라이팅(Technical Writing)이란?
기술적인 내용을 전달하는 글쓰기를 말한다. 이때 독자가 이해하기 쉽도록 작성하는 것이 중요하다. 일반적인 글을 작성할 때와는 다르게 테크니컬 라이팅은 '정확한 정보를 신속하게 전달하는 것'이 목표이다.
테크니컬 라이팅 가이드
그렇다면 테크니컬 라이팅은 어떻게 작성하는 것일까? 여러 기업들에서 문서의 통일성을 위해 '테크니컬 라이팅 스타일 가이드'를 정리해둔다. 이 글에서는 '토스(toss)'의 테크니컬 라이팅 가이드를 살펴볼 예정이다.
메인 화면
타기업의 라이팅 가이드 사이트를 처음 들어가보았을 때 작은 글씨로 방대한 양의 정보가 적혀있어서 어디서부터 읽어야할 지 난감했던 경험이 있다. 하지만 토스의 테크니컬 라이팅 가이드 사이트는 메인 화면 구성이 단순하고 직관적이다. 그렇기 때문에 테크니컬 라이팅을 처음 시도하는 사람들에게 많은 도움이 될 것이다.
메인 화면은 위와 같으며, 아래의 '문서 유형 정하기', '정보 구조 만들기', '문장 다듬기'가 테크니컬 라이팅 가이드의 주된 내용이다.
테크니컬 라이팅이 처음이라면 튜토리얼부터 정독하는 것을 추천한다.
튜토리얼에는 각 Step의 가이드가 어떻게 진행되는지 간략하게 설명되어있다.
화면 구성은 위와 같다. 왼편에서는 전체적인 목차를 볼 수 있고, 중앙에는 본문이 담긴 화면이 있다. 오른편에는 현재 보고있는 페이지의 목차가 담겨있다.
전공이 개발인 경우
만약 개발자의 입장에서 튜토리얼을 보게 된다면 '기본 문서 작성하기'부터 전부 다 읽어보는 것을 추천한다.
코드 작성법을 예시로 들기 때문에 기초부터 알아볼 수 있다.
전공이 개발 외인 경우
개발자가 아닌 입장이라면 튜토리얼에서 'AI 와 함께 쓰기'를 읽어보는 것을 추천한다.
AI에게 글쓰기를 맡기는 방법보다는 AI를 활용한 ‘수정’방법에 초점을 맞추고 있다.
튜토리얼에 대한 설명은 이쯤에서 마무리를 하고, 다음으로 Step 1. 에 대해 살펴보도록 하자.
Step 1. 문서 유형 정하기
Step 1. 에서는 문서의 유형을 정하고 그에 맞는 글을 작성하는 방법이 서술되어있다.
문서 유형은 크게 학습 중심, 문제 해결, 참조, 설명을 위한 유형으로 나뉘어져있고, 독자가 이 유형들을 언제 찾게 되는지 ‘독자의 목적’이라는 항목으로 설명해두었다. 글을 쓰는 사람이 어떻게 써야하는지 설명해둔 것이 아닌 독자의 입장을 설명해둔 것이 중요하다.
각 문서와 관련된 예시 글들도 하이퍼링크로 작성되어있으니, 개발자인 경우 본인의 목적에 맞는 글들은 한 번씩 읽어보는 것을 추천한다.
Step 2. 정보 구조 만들기
Step 2. 에서는 효과적인 정보를 제공하기 위한 구조 작성법이 서술되어있다.
한 페이지에서 하나만 다루기, 가치를 먼저 제공하기, 효과적인 제목 쓰기, 개요 빠트리지 않기, 예측 가능하게 하기까지 정보를 제공하는 글을 작성할 때 중요하게 여겨야하는 부분들을 다루고 있고, 특히 각각의 부분들마다 ‘체크리스트’를 포함하고 있기 때문에 전체를 읽을 시간이 없다면 체크리스트만이라도 확인하고 넘어가길 바란다. 이마저도 읽을 시간이 없다면 우측에 ‘ON THIS PAGE’를 눌렀을 때 나오는 간단한 정보들만이라도 확인하고 글을 쓰는 것을 추천한다.
Step 3. 문장 다듬기
Step 3. 에서는 독자의 입장에서 명확하고 이해하기 쉽도록 작성하는 법이 서술되어있다. 이 부분은 전공과 무관하게 ‘정보를 전달하는 글’을 작성하는 사람이라면 기본적으로 알아야하는 내용들을 담고 있다. Step 2. 와 마찬가지로 체크리스트가 있다. 여기에 추가적으로 ‘실습 문제’가 포함되어있어서 본인의 글쓰기 실력을 테스트해 볼 수 있다.
다양한 테크니컬 라이팅 가이드
지금까지 토스의 라이팅 스타일을 살펴보았다. 다른 기업들은 어떤 형식으로 스타일 가이드를 작성했을까?
'[TW] 테크니컬라이팅과 스타일 가이드'라는 글을 아래의 표로 정리해보았다.
(사진 클릭 시 해당 기업의 스타일 가이드 사이트로 이동한다.)
[TW] 테크니컬라이팅과 스타일 가이드
회사에서 진행 중인 사이드 프로젝트 때문에 다양한 스타일 가이드를 살펴봐야 했다. 그간 공부한 자료를 겸사겸사 정리했다.
medium.com
 | 개발자들의 문서 작업을 위해 마련한 가이드. (개발자가 문서 자료를 ‘문서’ 자체로 보기보다 소스 코드 작업과 유사하게 다뤘을 때 부담감이 덜해지고 효율이 올랐다고.) 구글의 개발 문서가 명확하고 일관되게 작성되도록 마련한 가이드. (참고: <구글 엔지니어는 이렇게 일한다>) 포맷 측면으로도 참고하기 좋은 가이드. | |
| Apple |   | 큰 틀에서의 목차 대신 A-Z까지 요소를 백과사전처럼 나열하여 각 요소의 표기법, 작성법을 정리해 놓은 가이드. |
| Microsoft |  | 구글 못지 않게 콘텐츠가 상세한 가이드. 어떤 요소를 사용하기 전, 이게 적절한지 test 해야할 때 스스로 점검해볼 수 있는 지점을 함께 안내하는 가이드. 예를 들어 jargon(약어)를 쓰기에 앞서 이것이 약어인지 아닌지 테스트해볼 수 있는 체크리스트를 제시. PDF 형식 다운로드도 가능. |
| GitLab |  | 목차가 Lists, Tables, Link 와 같은 식으로 나열되어 있어 직관적인 가이드. 깃랩의 모든 문서는 Markdown으로 작성되기 때문에, 일관된 형식을 위한 Markdown 작성법을 코드 블럭으로 안내한다. |
| Red Hat |  | 상당히 구체적인 지침을 담고 있고, 다른 기업 스타일가이드에는 없는 요소를 보는 재미가 있는 가이드. 예를 들어, 3.1. Overall Book Design에서는 제목, 제목 배치, 머리말, 초록 등 기술문서의 전반적인 레이아웃 형식을 다룬다. |
| mailchimp |  | 정확히 말하면 콘텐츠 작성 스타일 가이드. 보이스와 톤, 문법적 측면 뿐만 아니라 나이, 젠더, 장애 관련 용어를 언급할 때 어떤 용어가 적절하고 어떤 용어는 부적절한지 등을 안내하고 있다. 예를 들어 누군가의 연령을 이야기할 때 ‘16세’라는 객관적이고 정확한 표현을 사용하며, ‘old’, ‘young’, ‘elderly’ 같은 상대적인 표현을 지양할 것이라 써져 있다. |
마무리
지금까지 토스를 비롯한 다양한 기업의 라이팅 스타일 가이드를 살펴보았다.
테크니컬 라이팅의 실력 향상을 위해서라면 여러 기업의 라이팅 스타일 가이드를 그대로 따라하기보다는 참고하면서 자신만의 라이팅 스타일 가이드를 만들어가는 것이 중요하다. 만약 본인이 블로그에 작성한 글들의 스타일이 다르다면, 이 기회에 본인만의 라이팅 스타일 가이드를 확립해보는 것은 어떨까? 이러한 과정을 거치면 결과적으로 통일성 있는 블로그가 만들어지면서 방문하는 독자의 입장에서도 신뢰감이 느껴질 것이다.