이 글은 2025년 3월 19일에 진행된 구름 COMMIT <고객을 사로잡는 사용자 가이드 쓰기>의 내용을 정리한 글입니다.
테크니컬 라이팅이란 📝
테크니컬 라이팅(Technical Writing)이란 이번 세미나에서 다룰 사용자 가이드의 상위 개념으로,
"특정 독자를 대상으로 특정 목적의 정보를 전달하는 글쓰기"를 말한다.
문학 글쓰기와 테크니컬 라이팅
문학 글쓰기와 다르게 사실을 명확하고 간결하게 특정 대상 독자에게 직설적이고 순차적으로 전달하는 것이 목적이다.
그래서, 원칙을 가지고 연습을 한다면 누구나 잘 쓸 수 있다는 것이 큰 장점이다.
예를 들어보자.
먼저 문학 글쓰기의 예시는 다음과 같다.
나는 버튼을 조심스럽게 눌렀고, 어둠 속에서 작은 녹색 불빛이 천천히 퍼져나갔다.
같은 글을 테크니컬 라이팅에서는 다음과 같이 쓸 수 있다.
가운데 전원 버튼을 눌러 장치를 켭니다. 전원이 켜지면 LED 표시 등이 녹색으로 변합니다.
어떤 동작을 하면 어떤 반응이 나타나는지 사실만을 명확하고 간결하게 서술하고 있다.
테크니컬 라이팅의 범위
테크니컬 라이팅 범주 안에 드는 문서, 즉 기술문서의 범위는 어디까지일까?
제안서나 메일, 회의록도 기술 문서에 해당하는지 헷갈릴 수 있다.
하지만 특정 독자가 있다면, 넓은 범위에서 모두 기술 문서에 해당한다.
사용자 가이드란 📄
그중에서도 이번 세미나의 주제인 사용자 가이드에 초점을 맞춰보자.
사용자 가이드는 사용자가 제품을 빠르게 이해하고 활용하도록 지원한다는 점에서 중요한 문서이다.
대표적인 사용자 가이드로는 마이크로소프트 설명서가 있다.
핵심 역할
사용자는 즐기려고 가이드를 읽는 것이 아니라 문제를 해결하기 위해 읽는 것이므로 정확한 답변을 쉽고 빠르게 제공해야 한다.
다음과 같은 핵심 역할을 잘 기억해두자.
- 사용자 경험 개선
- 고객 지원 부담 감소
- 제품 신뢰도 향상
- 글로벌 확장 지원
사용자 가이드 쓰기 👩💻
사용자 가이드는 총 3단계로 나눠서 작성한다.
계획 수립
사용자 가이드를 쓰기 전 계획을 세우는 단계이다.
대상 독자 정하기
가이드에서 다룰 기술의 깊이를 지정하기 위해서는 대상 독자의 범주를 정해야 한다.
대상 독자는 크게 다음과 같이 나눌 수 있을 것이다.
- 개발자
- 기술 직군
- 비기술 직군
대상 독자에 따라 다음과 같이 개념과 전문 용어를 어떻게 서술할지 기준을 정할 수 있다.
(순서대로 개발자, 기술 직군, 비기술 직군)
만약 대상 독자의 범위가 넓다면, 잘 아는 사람들은 건너뛸 수 있도록 가이드하는 것도 중요하다.
가이드 유형 정하기
가이드의 유형으로는 빠른 시작 가이드, 튜토리얼, 매뉴얼, 레퍼런스, 문제 해결 가이드, 비디오 가이드, FAQ 등이 있다.
서비스 특성에 따라 가장 어울리는 가이드 유형을 정해야 한다.
일정 세우기
전체 단계인 계획 - 작성 - 고치기 / 검토에서
마지막 단계인 고치기 / 검토에 전체 일정의 40% 정도의 시간을 할애하는 것이 가장 이상적이다.
따라서 초안을 빠르게 작성하고 마지막 단계에 많은 시간을 쓰는 것이 좋다.
스타일 가이드 만들기
가이드는 함께 쓰는 경우가 많기 때문에 전체 문서의 일관성을 유지하기 위해 스타일 가이드를 잡는 것이 좋다. 시간이 걸리더라도 샘플 문서를 작성하고 어조, 템플릿, 스크린샷 환경, UI 요소 표현 등 스타일 요소 별로 가이드를 만들자.
스타일 요소 별로 살펴보자.
어조
크게 해요체와 합쇼체로 나눌 수 있다. 서비스의 어조에 맞추면 되지만, 기본적으로 사용자 가이드는 친절하고 정중한 합쇼체를 사용하는 것을 추천한다.
해요체: 버튼을 클릭해요.
합쇼체: 버튼을 클릭합니다.
UI 요소 표현
메뉴명이나 버튼명은 사용자 눈에 잘 보이게 표현하는 것이 좋다.
'작은 따옴표'를 쓰거나 굵게 쓰거나 [대괄호]로 쓸 수 있다.
일반적으로는 굵게 표시하는 경우가 많지만 불가능하다면 [대괄호]를 쓰기도 한다.
초안 작성
문서를 본격적으로 작성하는 단계이다.
3C 원칙
검토 단계에서 부담을 줄이려면 초안부터 3C 원칙에 맞추어 작성하는 것이 좋다.
(이 원칙은 문서 작성 뿐 아니라 모든 의사소통에 적용됨)
용어와 약어 풀이
독자가 모르는 용어를 다시 찾아보지 않도록, 전문 용어는 풀이를 넣는 것이 좋다.
약어는 문서에서 처음 나올 때 한 번 풀어쓰고, 이후에는 약어로 사용한다.
편의상 사용하는 약어가 아닌, 사전에 등재된 약어만 줄여써야 한다.
용어와 약어를 정리한 용어집을 따로 만들어 제공하는 것이 가장 좋다.
은어 사용에 주의
판교체라고 불리는, 흔히 회사에서 통용되는 은어를 공식 문서에 쓰지 않도록 주의한다.
만약 은어를 대체할 단어를 찾지 못하겠다면 상황을 설명해서 풀어쓴다.
엑박이 뜨면 (X)
이미지가 표시되지 않으면 (O)
객관적인 근거나 수치 제시
사용자가 명확하게 받아들일 수 있도록 객관적인 정보를 포함하는 것이 좋다.
앱 시작 시간이 너무 길면 알림을 보냅니다. (X)
앱 시작에 2초 이상 걸리면 알림을 보냅니다. (O)
대명사보다는 일반 명사 사용
문학에서는 대명사로 지칭하는 경우가 많지만, 사용자 가이드는 필요한 부분만 보는 경우가 많으므로 대명사보다는 단어를 다시 쓰는 것이 좋다.
새로 나온 공통 플랫폼을 알아보자. 이를 사용하면 유지보수 비용을 절약할 수 있다. (X)
새로 나온 공통 플랫폼을 알아보자. 공통 플랫폼을 사용하면 유지보수 비용을 절약할 수 있다. (O)
링크를 연결할 때는 어떤 링크인지 명확하게 적으면 독자의 불필요한 행동을 줄일 수 있다.
자세한 설명은 여기를 참고하세요. (X)
자세한 설명은 오류 코드를 참고하세요. (O)
쉽게 말하듯이 서술
돌려 말하지 않고 사실을 단정적으로 전달해야 명확한 정보를 전달할 수 있다.
결제 기능 편의를 제고하고자 익월 말까지 시스템을 정비할 예정입니다. (X)
결제 기능을 편하게 사용할 수 있게 다음 달 말까지 시스템을 정비할 예정입니다. (O)
의미없는 표현은 정리
'~을 진행한다'처럼 의미 없이 사용되는 표현은 줄이고 간결한 문장을 사용한다.
고객이 상품 등록 요청을 진행하면 담당자가 검토 처리를 한 후 5일 내에 결과를 전달하는 방식으로 이루어지고 있습니다. (X)
고객이 상품 등록을 요청하면 담당자가 검토 후 5일 내에 결과를 전달합니다. (O)
용어나 표현의 일관성을 유지
용어 통일안을 구성하여, 같은 용어는 일관성을 유지해서 사용한다.
인스턴스의 보안 그룹 ID를 지합니다. 시큐리티 그룹에는 instance와 통신할 수 있는 룰이 있어야 합니다. (X)
시각 자료
이미지, 도해, 도표 등 시각 자료는 제작에 많은 시간이 걸리지만 독자의 이해를 돕기에 가장 좋은 요소이다.
시각 자료를 활용할 때는 본문 내용과 일치하는지 확인하는 것도 중요하다.
아무런 설명 없이 시각 자료부터 제시하기보다는 자료를 소개하는 글을 먼저 제시해서 독자의 이해도를 높이는 것이 좋다.
글로벌 현지화
현지화는 단순 번역이 아닌 문화에 맞게 조정하는 과정이다.
현지 전문가의 도움을 빌려, 문화를 반영하는 것이 좋다.
스크린샷에는 최대한 텍스트를 표시하지 않고 숫자나 기호로 표기하고 본문에서 설명하는 것이 현지화에 좋다.
언어마다 같은 말도 길이가 다르므로 텍스트가 들어갈 공간은 50퍼센트 정도 여유를 두고 설계하자.
우리말 순화
정작 우리나라에서 쓸 기술 문서에 외국어가 많이 사용되는 경우가 있다. 다음과 같이 우리말로 순화해서 사용하는 것이 좋다.
- 적당한 우리말이 없다면 음차
- 전문 용어는 원문 병기
- 타사 서비스나 제품 이름은 고유 명사인 원문대로
고치기 / 검토
3단계 중 가장 중요한 단계로, 지금까지의 단계에서 해온 것을 모두 반복한다고 보면 된다.
문서 구조
목차 단계가 너무 깊어지면 목차의 역할을 하지 못 하는 것이다.
장제목을 제외하고 3~4 단계로 구성하는 것이 좋다.
만약 목차 단계가 깊어진다면 문서를 분리하는 것을 권장한다.
문장과 맞춤법
문장과 맞춤법은 문서의 신뢰도에도 영향을 준다.
어느 정도 맞춤법을 알고 있는 것이 좋지만, 도구의 도움을 빌리는 것이 정확하다.
동료 검토
시간을 내서 동료끼리 서로 바꿔 읽는 것을 추천한다.
이 과정으로 분석적 읽기를 연습하고 자신의 글을 되돌아 볼 수 있다.
한 번에 모든 항목을 검토하기보다는 1회차는 본문 위주, 2회차는 구조 위주, 3회차는 링크 테스트 등 집중해서 볼 부분을 정해서 여러 번 읽는 것이 좋다.
검토 방법
분석적 읽기를 할 때는 다음과 같은 방법을 활용한다.
- 객관화 - 하루 지나서 읽기
- 다른 감각 활용 - 소리 내어 읽기
- 매체 변경 - 인쇄해서 읽기
정리를 마치며
이번 세미나는 사용자 가이드를 잘 쓰는 방법을 다뤘지만,
결국 핵심은 '정보를 효과적으로 전달하는 글쓰기'의 본질에 관한 이야기였다.
대상 독자를 고려하고, 명확하게 쓰고, 불필요한 표현은 줄이고, 용어를 일관되게 사용하는 것.
이 모든 원칙은 사용자 가이드뿐 아니라 기획 문서, 개발 문서, 심지어 블로그 글에도 똑같이 적용된다.
무엇을 설명하든, 글은 결국 누군가를 위한 도구인 만큼, 그 글이 잘 쓰였는지보다, 잘 전달됐는지가 더 중요하다고 생각한다.
그래서 이 세미나에서 배운 내용을 가이드 작성에만 한정 짓지 않고,
앞으로 내가 쓰는 모든 글에 한 번씩 적용해 보려고 한다.
