1-8. Audience

Google Technical Writing Course - 1

글을 읽을 독자층을 정의하고, 그들이 무엇을 얻어갈지 정하며, 얻어갈 수 있도록 그들에게 맞춘 문서를 만드는 법에 대해 다루는 파트.

good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills

즉, 문서는 독자가 가지고 있지 않은, 그들에게 필요한 것을 제공해줘야 한다.

이번 파트의 목차는 아래와 같다.

Define your audience

작성할 문서의 예상 독자를 정할 때, 먼저 그들의 role(직업 또는 직군)을 확인한다.

예시는 아래와 같다.

Software engineers

Technical, non-engineer roles (such as technical program managers)

Scientists

Professionals in scientific fields (for example, physicians)

Undergraduate engineering students

Graduate engineering students

Non-technical positions

이러한 직업군에 따라 base로 공유하고 있는 지식, 그리고 전달 방식에 대해서도 아래와 같이 설명하고 있다.

SW의 엔지니어를 대상으로 할 경우 그들이 정렬 알고리즘이나 O(n)의 개념에 알고 있다고 가정하고 문서를 작성할 수 있지만, 비개발자를 대상으로 하는 문서에 아무런 설명 없이 O(n)이라는 텍스트를 쓰면 안된다. Tech 문외한은 O(n)이 시간 복잡도라는 개념을 나타낸다는 것을 모른다.

같은 연구에 대한 것이라도, 의사(physicians)를 대상으로 한 연구 보고서와 일반 대중(a lay audience)을 대상으로 한 신문 기사가 같을 수는 없다.

대학원생을 대상으로 하는 새로운 머신러닝 기법에 대한 설명은 1학년 학부생을 대상으로 할 때와 달라야 한다.

또한, 같은 직업 또는 직군이더라도 그 안에서 각각의 전문 영역이 다르다.

가령 같은 의료 직군 내에서도, 심장 전문가가 일반적인 SW 엔지니어보다 귀와 관련된 문제에 대해 더 잘 알기야 하겠지만 청각사에 비할 바는 되지 못한다.

따라서 작성하고자 하는 주제에 대해 예상 독자가 얼마나 알고 있는지(proximity to the knowledge)에 대한 고려도 필요하다.

마지막으로, 시간 또한 고려 대상이다.

가령 대부분의 SW 엔지니어가 미적분을 배우지만, 현업에 종사하는 SW 엔지니어 중 과연 얼마나 그 내용을 제대로 기억할까? 또한 같은 전문 영역을 다루더라도 그 분야에 오래 종사한 엔지니어가 신입 엔지니어보다 더 폭넓은 지식을 갖고 있는 것이 일반적이다. 즉 예상 독자가 그 분야에 얼마나 숙달되었는지도 고려해야 한다.

Sample audience analysis

예상 독자 분석은 아래와 같이 진행할 수 있다.

먼저 독자의 role을 정의한 후에, proximity를 정리했다.

또한 proximity를 정리하면서 'time'에 대해서도 함께 고려하고 있다.

The target audience for Project Zylmon falls into the following roles:

Software engineers

Technical product managers

The target audience has the following proximity to the knowledge:

My target audience already knows the Zyljeune APIs, which are somewhat similar to the Zylmon APIs.

My target audience knows C++, but has not typically built C++ programs in the new Winged Victory development environment.

My target audience took linear algebra in university, but many members of the team need a refresher on matrix multiplication. (→ time)

Determine what your audience needs to learn

독자가 문서를 읽으면서 배워가야 할 것, 또는 독자가 이 문서를 읽고 난 후 수행해야 하는 일을 목록으로 정리해본다.

아래 예시는 독자가 수행해야 하는 일을 목록화했다.

After reading the documentation, the audience will know how to do the following tasks:

Use the Zylmon API to list hotels by price.

Use the Zylmon API to list hotels by location.

Use the Zylmon API to list hotels by user ratings.

반면 디자인 스펙에 대한 문서의 경우, 리스트는 독자가 직접 수행할 일보다는 배워갈 수 있는 정보 위주로 리스트를 작성하다. 아래 예시와 같다.

After reading the design spec, the audience will learn the following:

Three reasons why Zylmon outperforms Zyljeune.

Five reasons why Zylmon consumed 5.25 engineering years to develop.

Fit documentation to your audience

타겟 독자층에 맞는 문서를 작성하기 위해, 아래 요소들을 고려한다.

Vocabulary and concepts

'proximity'에 초점을 둘 것.

내가 속한 팀의 사람들이 이해하는 약어를, 다른 팀의 사람들도 이해할 수 있는가?

일반적으로 타겟 독자층이 넓어질수록 보다 많은 설명이 필요하다.

대부분의 업무를 공유하는 아주 가까운 팀원들을 대상으로 한 것이 아닌 이상

대체로 스스로 생각하는 것보다 더 많은 설명을 해야 한다.

어휘 사용법 자체에 대해서는 이전 Words 글을 참고:

https://brunch.co.kr/@eebbc6d856334ef/29

Curse of knowledge

전문가들이 종종 겪는 것으로, '아는 것이 독'인 경우.

신입은 본인만큼 알지 못한다는 것을 간과하여 발생하며, 아무 생각 없이 툭 스쳐 지나가듯 잠깐 언급하고 넘어가는 미묘한 상호작용이나 복잡한 시스템을 초보자는 이해하지 못할 수도 있다. (Novices might not understand explanations that make passing reference to subtle interactions and deep systems that the expert doesn’t stop to explain.)

Exercise

1. 아래 글의 타겟 독자층이 프로그래밍 경험이 전무한 의사 직군이라고 할 때, 'curse of knowledge'에 해당하는 부분들 찾아보기.

C is a mid-level language, higher than assembly language but lower than Python and Java. The C language provides programmers fine-grained control over all aspects of a program. For example, using the C Standard Library, it is easy to allocate and free blocks of memory. In C, manipulating pointers directly is mundane.

밑줄친 부분은 내가 짚은 것, 빨간색으로 표기한 것은 모범답안이다.

파이썬과 자바는 둘째치고, 심지어 "program"이라는 용어 자체도 주의해야 할 줄이야.

2. 동일한 글이 파이썬에는 익숙하지만 C는 처음 다뤄보는 학부생을 대상으로 한다고 할 때도 'curse of knowledge'의 영향을 받는가?

→ 그렇다. 왜냐하면 일반적인 파이썬 프로그래머는 'manipulationg memory or pointers'에 익숙하지 않기 때문이다. 타겟 독자층이 이와 같을 경우, 아예 첫 문단에서 C와 파이썬을 비교하며 시작하는 것이 좋다.

Simple words

맞다. 너무 어려운 영단어 쓰지 말자!!

모두가 영어가 모국어인건 아니다!!

Cultural neutrality and idioms

문서를 작성할 때 특정 문화에 대해 잘 알아야만 이해할 수 있는 비유나 은유는 피하라는 것.

아래 예시를 보면 Frambus라는 프로그램을 야구 용어로 비유해서 설명하고 있다.

If Frambus 5.0 was a solid single, Frambus 6.0 is a stand-up double.

solid single은 확실한 1루타, 즉 성공적이지만 대단하지 않은 결과를 비유하고

stand-up double은 서서 들어간 2루타, 즉 더욱 인상적이고 나아진 결과를 나타낸다고 한다.

즉 Frambus 5.0도 나쁘지 않았지만 6.0이 더 나아졌다는 의미.

이는 전형적인 미국 스타일의 관용구(as American as apple pie)로, 당장 야구에 문외한인 나부터 무슨 뜻인지 몰라서 챗GPT한테 물어봤다.

여담으로, 야구라는 스포츠 자체가 미국, 일본, 한국 등 일부 문화권에서만 대중적이며

프랑스, 독일, 인도, 중국 등 많은 나라에서는 야구가 대중적이지 않다고 한다.

따라서 위의 문장은 문화적으로 치우쳐져 있는 대표적인 예시로 볼 수 있다.

관용구(Idiom)란 단어를 직역했을 때와는 다른 비유적 의미를 가진 표현으로, 아래 2가지 예시가 있다.

a piece of cake (식은 죽 먹기)

Bob's your uncle (끝났어! 아주 쉬워!)

첫 번째는 미국, 두 번째는 영국에서 흔히 쓰이는 관용구다.

만약 대상 독자가 미국인이라면 첫 번째 관용구, 영국인이라면 두 번째 관용구를 써도 되겠지만

국제적인 독자를 대상으로 한다면 "this task is done"등의 명확한 표현을 써야 한다.

결국 관용구도 "curse of knowledge"로, 사용자는 이것이 관용구인지조차 모른채 당연히 누구나 이해할 것이라고 생각하지만 실상은 그렇지 않다.

추가로, 번역기를 사용하는 경우 관용구가 많으면 정확도가 떨어지는 점도 참고할 것.

Exercise

1. As of Version 3.0, it was still kosher to call the Frambus method.

→ "kosher"란 유대교 율법에서 허용된 음식을 나타내는 것으로, 여기서는 "허용된 것"이라는 의미로 쓰였다.

kosher에 대해 이해하지 못하는 독자들을 고려해 "acceptable usage"등의 명확한 표현으로 대체한다.

2. Deciding which BlogResource constraints are combinable is a sticky wicket.

→ "sticky wicket"이란 "어려운 문제"를 나타내는 영국식 속어로, "challenging problem"등의 표현으로 대신할 수 있다.

3. Be that as it may, you still have to write unit tests.

→ 몰랐는데, "Be that as it may" 자체도 관용구라고 한다. 한국 사람이라면 수능이나 토익 공부하면서 많이 접했을 텐데, 이것도 사용상 주의해야겠다. "However" 같은 단순한 연결어로 바꾸는 것이 좋다.

출처 : https://developers.google.com/tech-writing/one/audience