1-2. Words
Google Technical Writing Course - 1
목차는 다음과 같다.
각 파트의 내용을 간단히 정리하면 아래와 같다.
Define new or unfamiliar terms
타겟 독자에게 익숙하지 않은 단어를 쓰거나 새로운 단어를 만들어내는 경우, 충분한 설명과 명확한 정의를 해주라는 내용.
Use terms consistently
문서 안에서 특정 단어를 쓰기로 결정했다면, 그 단어를 쭉 이용할 것.
아래 예시처럼, 처음에 'Protocal Buffers'라고 지칭한 대상을 뒤에서는 'protobufs'라고 사용하면 안 된다.
Protocol Buffers provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.
만약 protobufs라는 축약어가 쓰고 싶다면, 아래와 같이 처음에 명시를 해주자.
Protocol Buffers (or protobufs for short) provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.
하나의 대상을 지칭할 때 여러 가지 표현을 쓰면 독자는 이 두 가지가 같은 대상을 지칭하는지, 아니면 차이가 있는 것인지 헷갈린다.
사실 단어의 일관성에 대한 문제는 회사에서 일할 때 가장 심각하게 느껴지는 부분이다. 고객이나 관계부서는 물론이고, 같은 팀 내에서도 사람마다 부르는 명칭이 다르다. 하지만 다들 이해를 못해도 모호하게 넘어가는 분위기라, 질문하기도 애매할 때가 많다. 그러다가 나중에 일이 배로 복잡해지는 경우도 수두룩했다. 지금이야 경험이 조금 쌓인 만큼 상대방이 대충 던져도 알아듣는 내용이 늘어났지만, 신입사원 때는 정말 고역이었다.
Use acronyms properly
축약어는 쓸 경우, 처음에는 전체 단어와 축약어를 모두 명시한다.
구체적으로, Full Term을 풀어 쓴 바로 뒤에 괄호 안에 축약어를 나타내준다.
예를 들어 아래와 같다.
This document is for engineers who are new to the Telekinetic Tactile Network (TTN) or need to understand how to order TTN replacement parts through finger motions.
이후에는 전체 단어 또는 축약어 둘 중 하나로 통일해서 문서를 작성한다.
어떤 때는 축약어, 어떤 때는 전체 단어를 쓰는 일은 없도록 한다.
그렇다면 전체 단어와 축약어 중 어느 것을 써야 할지는 어떻게 정할까?
이에 대해서는 아래와 같은 축약어 가이드라인이 있다.
- 축약어를 쓸 때 글이 훨씬 짧고 간단해질 때 사용할 것.
- 축약어가 문서 내에서 여러번 등장할 경우에 사용할 것.
축약어를 사용하면 문서 자체의 관점에서는 장황함을 줄이고 간단명료하게 작성할 수 있다. 하지만 독자는 머릿속에서 그 축약어를 전체 의미로 번역하는 과정을 한 번 거쳐야 하기 때문에, 오히려 처음에는 정보를 받아들이는 데 있어 시간이 더 걸린다. 축약어가 문서 내에서 여러 번 등장할 경우, 이미 익숙해진 독자는 이후에는 빠르게 내용을 이해할 수 있지만, 몇 번 등장하지도 않는 단어를 축약해서 사용하면 외려 독자에게는 불친절한 문서가 될 수 있는 셈이다.
Recognize ambiguous pronouns
애매모호한 대명사 표현을 주의하라.
특히 기술 문서에서 주의해야 하는 대명사는 It & They (또는 them, their) 과 This & That.
여기서 지적하는 '애매모호'란 대명사가 무엇을 가리키는지 확실하지 않은 경우이다.
예를 들어 아래와 같다.
Python is interpreted, while C++ is compiled. It has an almost cult-like following.
여기서 It은 Python인가? 아니면 C++인가?
개발자라면 It이 Python을 가리킨다고 한 번에 이해할지도 모른다.
하지만 나 같은 비개발자라면, 아래처럼 챗GPT한테 물어본 다음에야 이 문장을 이해할 수 있다.
- 나 : 왜 이 문장에서 It이 C++이 아니라 Python이야?
- 챗GPT : "cult-like following"이라는 표현은 실제로 Python 사용자 커뮤니티를 묘사할 때 종종 쓰이는 말이야. Python은 단순하고 배우기 쉬운 문법, 풍부한 생태계, 열정적인 커뮤니티로 유명하거든. 반면 C++는 그런 표현보다는 복잡하지만 강력한 언어라는 쪽에 더 가깝지.
또 다른 예시는 아래와 같다.
Running the process configures permissions and generates a user ID. This lets users authenticate to the app.
여기서 "This"는 무엇을 가리키는가? user ID? 권한 설정하는 것(configures permissions)? 아니면 이 모든 행위? 이 작업에 대해 이해하고 있는 사람은 이렇게 깊이 생각할 것도 없이 This가 무엇을 가리키는지 알 수 있겠지만, 나 같은 문외한에게는 다소 혼란스럽게 다가온다.
실제로 일하거나, 맨땅에 헤딩하듯 개발 공부를 하려고 했을 때 영문서를 접할 때마다 수도 없이 부딪혔던 문제다. 작업 시간이 늘어나고 능률이 떨어지는 주범 중 하나였고, 이해하기를 포기하고 늘어졌던 경험들이 새록새록 기억난다.
어쩌면 이 글의 작성자는 이 This가 애매하다는 생각조차 하지 못했을 것이다 - 그 함정을 비집고 들어가는 것이 Technical Writer의 역할일까?
이 문장을 명료하게 고치면 아래와 같이 고칠 수 있다.
- This user ID lets users authenticate.
- The process of configuring permissions lets users authenticate.
- The combination of permissions and a user ID lets users authenticate.
대명사는 잘못 쓰면 애매하고, 기술 문서의 정보 전달력을 떨어뜨린다.
하지만 잘 활용하면 문서를 훨씬 간단명료하게 작성할 수 있고, 사실상 영어는 대명사와 뗼래야 뗄 수 없는 언어이다.
따라서 아래와 같은 가이드라인을 따르도록 한다.
- 명사를 먼저 사용한 이후에 대명사를 사용한다.
- 대명사는 최대한 명사 가까이에 둔다. 일반적으로 대명사가 명사에서 5개 단어 이상 떨어지면, 명사를 한 번 더 써주는 것을 고려해보자.
- 명사와 대명사 사이에 새로운 명사를 쓰지 않도록 한다.
