시작하며
안녕하세요. 카카오엔터프라이즈 테크니컬라이팅팀의 Crystal(김유리)과 Sandy(차신영)입니다.
오늘은 테크니컬 라이팅에서 일반적으로 쓰이는 테크니컬 라이팅 4대 원칙을 소개해 드리고자 합니다. 앞선 포스팅에서 이메일 작성을 포함한 회사 내에서 작성하는 모든 문서는 기술문서에 해당하며, 이 문서를 작성하는 이들은 일종의 테크니컬 라이팅을 하고 있다고 설명드렸는데요. 따라서 회사 내에서 문서나 이메일을 작성 시 테크니컬 라이팅의 대원칙을 숙지하고 이를 활용하면 글쓰기에 큰 도움이 될 것입니다.
본격적으로 테크니컬 라이팅 4대 원칙을 설명하기 전에, 미국의 언론인이자 퓰리처상의 창시자인 조셉 퓰리처의 명언을 하나 소개하고 싶은데요.
테크니컬 라이팅 4대 원칙에 대해 설명하다가 갑자기 조셉 퓰리처의 명언을 왜 소개하는지 궁금해하시는 분들도 계실 텐데요. 그 이유는 차차 설명드리기로 하고, 본격적으로 오늘의 포스팅을 시작하도록 하겠습니다.
① 명확성 (Clarity)
테크니컬 라이팅의 첫 번째 원칙은 명확성(Clarity)입니다. 명확한 글이란 핵심어나 핵심 문장이 모호하게 사용되지 않고, 대상 독자가 기술문서를 읽을 때 내용의 모호함이나 혼란 없이 한 번에 이해하도록 하는 글입니다. 어떤 문서를 읽을 때 독자 입장에서 이해가 가지 않아 특정 부분을 몇 번이고 다시 읽게 된다면, 이는 명확성이 떨어지는 글입니다.
실제 예시를 보겠습니다.
저는 입사 초기에 개발 문서에서 위의 문장을 읽고 한참 동안 혼돈의 늪에 빠진 적이 있습니다. 그 당시, 저는 일반 독자로서 카카오 계정과 헤이카카오 계정에 대한 이해가 전무한 상태였습니다. 따라서 'Kakao i 음성인식 서비스를 사용하려면 헤이카카오에 가입하라고?' '그런데 카카오 계정을 어디에 사용해야 하는 건가?'라며 한참을 생각했습니다. 이 한 문장을 이해하기 위해 같은 문장을 수십 번 읽어봐야 했습니다.
여러분들은 어떠신가요? 이미 서비스 흐름을 잘 알고 있는 사내 개발자가 아니라면, 제가 이 글을 처음 읽었을 때와 마찬가지로 혼란스러울 텐데요.
이렇게 명확성이 모호해지는 문제는 대부분의 경우 대상 독자를 제대로 파악하지 못해서 발생합니다. 실제 개발자들이 작성한 초안을 받아보면 중간에 퍼즐이 하나 빠진 글처럼 1번 설명에서 3번 순서로 바로 넘어간다거나, 아예 사전 작업에 대한 언급을 생략하고 본론부터 설명을 시작하는 경우가 많은데요. 이에 대해 개발자들에게 질문을 하면 대부분 다음의 답변이 되돌아오곤 합니다.
이 내용은 개발자들이라면 다 아는 내용인데 적어야 하나요?
결론부터 말씀드리면, "네, 다 아는 내용이라도 적어야 합니다"입니다. 왜냐하면 "개발자들이라면 다 안다"라는 생각은 굉장히 주관적일 수 있기 때문입니다. 독자가 개발자라고 하더라도 경력이나 실력에 따라 초급/중급/시니어 개발자로 나뉘기도 하고, 대부분의 기술문서는 사내가 아닌 외부에 공개되므로 대학생들이나 외부의 초급 개발자들도 쉽게 따라 할 수 있는 정도의 상세한 문서여야 합니다.
| 원본 | 수정본 | 수정 이유 |
| 출처가 명확하지 않은 APK를 설치하지 않습니다. | 출처가 명확한 APK 파일만 설치합니다. | 이중 부정 지양 |
| 편집 버튼이 클릭되어야 해당 항목을 편집할 수 있습니다. |
사용자가 편집 버튼을 클릭해야 해당 항목을 편집할 수 있습니다. |
수동 표현 지양(사람이 주어일 때) |
| 카카오 뮤직 서비스가 오픈합니다. | 카카오 뮤직 서비스를 오픈합니다. | 문맥에 맞는 조사 사용 |
| 아래의 3가지 항목에 대한 설명을 확인하시고 설정하세요. |
아래의 3가지 항목에 대한 설명을 확인 후 설정하세요. |
중복 높임 지양 |
② 간결성 (Conciseness)
테크니컬 라이팅의 두 번째 원칙은 간결성(Conciseness)입니다. 간결성이란 특정 독자가 기술적인 내용을 신속하고 정확하게 이해할 수 있도록 미사여구나 감탄사 등을 사용하지 않고, 간단하고 쉬운 단어와 간결한 문장을 사용하는 것입니다. 문장을 길고 복잡하게 복문으로 써야 더 있어 보이고, 더 많은 정보를 담게 될 것이라는 생각은 금물인데요. 기술문서에서는 "~은 ~입니다."라는 형식의 단문을 사용할 때 더욱 명확하고, 가독성이 높은 글을 작성할 수 있습니다. 간결성 원칙은 기술문서뿐만 아니라 일반 글쓰기에도 적용되는데요. 유시민 작가는 <유시민의 글쓰기 특강>이라는 책에서 단문을 사용한 글쓰기의 중요성을 피력하기도 했습니다.
단문의 중요성은, 복문의 단점을 생각해보면 이해가 쉬운데요. 다음의 예시를 살펴보도록 하겠습니다.
간결성 원칙에 따라 수정문에서는 A 속성에 대한 정의를 직관적으로 한 줄로 정리하고, A 속성과 관련한 부연 설명을 다음 문장에 대쉬 부호를 사용하여 정리했습니다. 필요한 정보는 모두 전달했는데도, 문장 길이는 줄어들고 가독성도 개선되었습니다.
| 원본 | 수정본 | 수정 이유 |
| 인증 메일을 성공적으로 전송했습니다. | 인증 메일을 전송했습니다. | 불필요한 부사 사용 지양 |
| 선택하신 파일을 삭제합니다. 정말 삭제하시겠습니까? | 선택한 파일을 삭제하시겠습니까? | 불필요한 수식어 사용 지양 |
| 등록된 시간 만큼은 근무시간에 포함되지 않습니다. | 등록된 시간은 근무시간에서 제외됩니다. | 긍정문을 사용하여 간결한 문장 지향 |
| 세션 정보는 지속적으로 유지됩니다. | 세션 정보는 유지됩니다. | 한자 사용 시, 중복 표현 사용 지양 |
③ 정확성 (Accuracy)
테크니컬 라이팅의 세 번째 원칙은 정확성(Accuracy)입니다. 정확성이란 독자가 필요로 하는 정보를 기술적 오류 없이 정확하게 제공하는 것을 말합니다. 명확성과 간결성이 떨어지지만 정확성이 확보된 기술문서라면, 독자들은 시간이 많이 걸린다 해도 결국에는 해당 문서를 이해할 수 있습니다. 하지만 잘못된 정보가 포함된 기술문서라면 상황은 달라집니다. 독자에게 무한대의 시간이 주어진다고 해도 해당 문서의 내용을 절대 파악할 수 없게 됩니다.
저는 얼마 전 내부 문서를 참고하여 샘플 봇을 만들어보려고 했는데요, 바로 첫 장부터 막히고 말았습니다. 바로 변경된 UI 텍스트가 문서에 제대로 반영되어있지 않았기 때문입니다. 문서의 콘텐츠뿐만 아니라 이런 UI 텍스트가 제대로 업데이트되지 않은 경우에는 문서의 신뢰도에 상당한 영향을 미치게 됩니다. 해당 몇 문장에만 오류가 있다고 할지라도 나머지 콘텐츠까지 오류가 있을 것이라는 합리적 의심을 가능하게 합니다.
역시 예시를 살펴보겠습니다.
얼핏 읽으면 어떤 부분이 틀렸는지 파악할 수 없지만, “카카오톡 플러스 친구”가 “카카오톡 채널”로 명칭이 변경된 것이 문서에 제대로 반영되지 않았기 때문에 독자가 해당 메뉴를 찾을 때 혼란을 겪을 수 있습니다.
| 원본 | 수정본 | 수정 이유 |
| 가로 크기: 800 | 가로 크기: 800 px | 정확한 단위 사용 |
| 댓글은 최소 10자까지 입력해야 합니다. | 댓글은 10자 이상 65자 이하로 입력해야 합니다. | 최소/최대 값 등 정확한 내용 기입 |
| 사전 설정은 이곳을 참고해 주세요. | 사전 설정은 사전 설정 챕터를 참고해 주세요. | 지시 대명사 사용 지양 |
④ 일관성 (Coherence)
마지막으로 네 번째 원칙은 일관성(Coherence)입니다. 문서에 용어, 표현, 그리고 어조 등을 일관성 있게 사용하는 것을 말합니다. 창작 글쓰기에서는 매번 같은 표현을 다르게 변형하여 독자에게 다양한 즐거움을 줄 수 있지만, 테크니컬 라이팅에서는 독자 입장에서 조금이라도 오해할 만한 여지를 남기면 안 되기 때문에 문서의 일관성 유지가 필수입니다. 특히 한번 언급된 단어를 다른 방식으로 언급하는 것은 독자에게 큰 혼란을 줄 수 있고, 결과적으로 문서의 신뢰도와 가독성이 저하됩니다.
다음 예시를 살펴보겠습니다.
예시에서는 빌더와 관련하여 "봇빌더"와 "카카오 i 오픈빌더"라는 용어가 등장합니다. 저는 처음 이 문장에서 언급된 “봇빌더”와 “카카오 i 오픈빌더”가 각각 다른 빌더를 지칭하는 것이라고 생각했습니다. 하지만 “카카오 i 오픈빌더”가 정식 명칭이며, "봇빌더"라는 용어는 사내에서 “카카오 i 오픈빌더”를 활용하여 봇을 생성한다는 함축적인 의미로 해석하여 표현을 하였습니다. 이와 같이 하나를 지칭하는 용어를 다양한 방식으로 사용하게되면 오해를 불러 일으킬 수도 있기 때문에 공식적인 문서에서는 사용을 지양해야 합니다.
| 원본 | 수정본 | 수정 이유 |
| 오픈빌더, 봇빌더, 챗봇빌더, 보이스봇 빌더 | 카카오 i 오픈빌더 | 일관된 명칭 사용 |
| 자동 로그인을 체크합니다. 자동 로그아웃을 선택합니다. |
자동 로그인을 선택합니다. 자동 로그아웃을 선택합니다. |
일관된 표현 사용 |
| 자동 방지 문자를 정확하게 타이핑합니다/칩니다. | 자동 방지 문자를 정확하게 입력합니다. | 일관된 표현 사용 |
마치며
위에서 살펴본 테크니컬 라이팅 4대 원칙은 이전 포스팅에서도 설명드렸듯이 테크니컬 라이팅이 하나의 전문 학위 분야로 정착된 해외에서 여러 학자들이 공동으로 합의한 대원칙입니다. 미국의 경우, 이공계 졸업생들이 기술적 글쓰기에 대한 일정 수준에 도달하지 못하면 테크니컬 라이팅 관련 수업을 이수해야 하는 학교도 있습니다. 대표적으로 MIT 공과대학은 대학원 신입생들을 대상으로 매년 GWE(Graduate Writing Exam, 대학원 작문 시험)를 실시하는데요. 학생들은 4~5개의 기술적 주제의 아티클을 읽고 750-1500단어 내외의 에세이를 쓰게 되는데, 논리적이며 명확하고 정확하게 설명해야 합니다. 평균적으로 학생들이 하나의 에세이를 작성하는데 4~7시간 정도가 소요되며, 또한 평가자들은 2~3시간에 걸쳐 에세이를 엄격하게 평가한다고 하니 학생들의 입장에서는 여간 부담이 아닐 수 없습니다. 이 시험에 통과하지 못한 학생들은 어떻게 될까요? 학교 측에서 마련한 테크니컬 라이팅 워크숍과 특별 강좌를 이수하게 됩니다. 이 강좌에서도 오늘 설명드린 4대 원칙이 중점적으로 다뤄집니다.
자, 이제 서두에서 언급한 조셉 풀리처의 명언을 다시 보겠습니다.
"짧게 써라"라고 시작하는 문장은 테크니컬 라이팅 대원칙 중 "간결성"을, "명료하게 써라”라는 문장은 "명확성"에 해당합니다. "그림처럼 써라"라는 문장은 이번 포스팅에서 언급하지는 않았지만, 독자가 어떤 시스템이나 기능의 아키텍쳐를 보다 쉽게 이해할 수 있도록 논리적으로 기술하거나 개발 시나리오나 개발 흐름 등의 시각 자료를 활용하는 것입니다. 마지막으로 무엇보다 “정확하게 써라” 라는 문장은 정확성 원칙에 대입할 수 있습니다.
카카오엔터프라이즈의 테크니컬라이팅 팀에서는 테크니컬 라이팅 4대 원칙인 정확성, 명확성, 간결성, 일관성을 유지하기 위해 ISO 표준과 테크니컬 라이팅 매거진 구독, 스타일 가이드 및 용어 사전 정리, 문서 종류별 템플릿 제작 등의 여러 노력을 기울이고 있습니다. 이 밖에도 사내 개발자들을 대상으로 한 테크니컬 라이팅 사내 교육도 야심차게 준비하고 있는데요. 강의에서도 오늘 설명드린 테크니컬 라이팅 4대 원칙을 중점적으로 다룰 예정이므로, 부디 오늘 포스팅을 잘 기억해 주세요. 감사합니다 🙂
김유리(Crystal)
사용자의 입장에서 생각하고, 개발자와 원활한 소통을 할 수 있는 Communication Skill을 가진 Technical Communicator입니다. 카카오엔터프라이즈의 값진 기술들을 정확하고 명확하게 전달하고, 신뢰를 쌓을 수 있는 문서를 만들고자 합니다.
차신영(Sandy)
산더미처럼 쌓여진 문서 정리, 새로운 문서화 도구 테스트, 그리고 구글링이 취미인 Technical Communicator입니다.
댓글