문서화를 비롯한 모든 글쓰기는 가장 쉬운 소통수단입니다. 하지만 아이러니하게도 '좋은 글쓰기'는 어렵습니다.
본 포스팅에서는 나의 의견 및 정보를 쉽고 명확하게 전달하는 방법을 다루고 있습니다. 간단한 원칙을 바탕으로 더 나은 글쓰기를 지향하고, 원활한 의사소통을 수행하고자 합니다.
또한, 아래와 같은 소주제를 담고 있습니다.
✔️ 글쓰기가 왜 어렵고 중요한지 ✔️ 나쁜 글쓰기는 어떻게 작성되는지 ✔️ 좋은 글쓰기는 어떻게 작성되는지
📝 테크니컬 라이팅이란?
1) 무엇인가?
안녕하세요 저는 우주라고 합니다. 카카오엔터테인먼트에서 개발자로 일을 하고 있는데 업무에 참고할 문서들을 찾다 보면 히스토리 파악이 안 되는 문서도 있고 내용이 이어지지 않는 문서도 있고 하다 보니 이런 문서화 같은 걸 어떻게 잘할 수 있는지를 좀 공유해볼까 해서 본 포스팅을 준비하게 됐고요. 사실 어찌 보면 글은 가장 친숙한 표현 수단이지만 이게 또 실제로 잘하는 건 어렵거든요. 그래서 오늘 공유하려는 주제로 테크니컬 라이팅을 준비했습니다.
여러분이 독자의 관점으로 위 소개글을 읽었다고 가정했을 때, 어떤 정보를 습득할 수 있을까요? 두세 차례 읽어야 '테크니컬 라이팅을 설명하겠다'는 내용을 알 수 있습니다.
단순한 소개글에 불과하지만 쉽게 읽히지 않는 것 같습니다. 그래서 위 소개글을 다음과 같이 수정해보았습니다.
우리는 살면서 문서를 포함한 많은 글을 접합니다. 하지만 모든 글이 읽기 쉽거나 읽기 좋게 정리되어있지는 않습니다. 그로 인해 독자는 글 내용을 이해하기 위해 많은 공을 들이게 됩니다. 이렇듯 글은 친숙하지만 어려운 표현 수단입니다.
글을 독자에게 더 쉽고 정확하게 전달하는 것. 제가 여러분과 나누고자 하는 주제입니다.
그렇습니다.
글을 독자에게 더 쉽고 정확하게 전달하는 것,
제가 여러분과 나누고자 하는 주제입니다.
2) 왜 하지 못했는가?
많은 분들이 테크니컬 라이팅의 존재를 알고 있습니다.
하지만 테크니컬 라이팅을 실제로 문서에 적용해본 적은 거의 없습니다.
왜냐하면 아래와 같은 이유 때문인데요.
잘 모른다.
바쁘다.
귀찮다.
좋은 테스트 코드를 작성하기 어려운 이유와 비슷하죠.
그 중요성 또한 테스트 코드와 비슷합니다.
중요한 건 알지만... 바빠서 하지 못했다.
시간적 여건이 되지 않는다라고들 하지만 중요한 기술 중 하나라고 생각합니다.
테크니컬 라이팅이 중요한 이유는 다음과 같습니다.
아무리 많은 정보를 알고 있어도 전달하는 방식에 따라,독자에게 전달되는 정보의 양이 제한됩니다.
좀 더 간략하게 벤 다이어그램으로 표현해봤습니다.
이러한 이론적인 내용을 인지하고 있음에도 불구하고 테크니컬 라이팅은 늘 후순위로 미뤄집니다.
직접적인 개발 기술도 아니고, 재미도 없다고 느껴지기 때문입니다.
여전히 재미는 없지만공돌이의 입장에서 더 쉽게 와닿을 수 있는 예시를 가지고 테크니컬 라이팅을 적용하는 방법에 대해 공유하고자 합니다.
나를 위해, 상대를 위해
📝 테크니컬 라이팅의 대원칙
1) 어떤 걸 하는가?
테크니컬 라이팅의 상세 원칙들을 설명드리기 앞서
하나의 맥락을 유지할 수 있도록 대원칙을 정의하고자 합니다.
🎯 목표
우리의 최종 목표는 '정보를 독자에게 효과적으로 전달하는 것'입니다. 테크니컬 라이팅은 목표를 위한 수단으로 사용합니다.
📍원칙
그러기 위해서는
내가 말하고 싶은 내용만 쓰는 것이 아니라,상대가 알아야 할 내용을 쉽게 알려줘야만 합니다.
독자n명의 시간 대신,나 하나의 시간을 더 할애해야 합니다.
이렇게 2개의 큰 대원칙을 가져갑니다.
📝 테크니컬 라이팅의 상세 원칙
이미 테크니컬 라이팅을 위한 기술이나 원칙을 설명하는 훌륭한 자료들이 많습니다.
이제부터 소개해드릴 상세 원칙은 위 자료들을 포함하여 위키백과, 구글 테크니컬 라이팅 코스 등에서 발췌한 내용입니다. 그 내용을 제가 정리하고, 일부 추가한 내용들로 구성되어 있습니다.
글쓰기에는 3가지 단계가 있습니다.
글을 쓰기 전 단계, 글을 쓰는 단계, 검토 단계, 다시 말해 글 쓰기의 전, 중, 후로 나눌 수 있습니다.
각 단계에 맞는 테크니컬 라이팅 상세 원칙들을 예시와 함께 알아보겠습니다.
1) 쓰기 전
글을 쓰기 전에는 간단하게라도 어떤 내용을 어떻게 쓸지 계획을 정리합니다.
2가지 대원칙인
'독자에게 필요한 내용을 작성한다.'
'나의 시간을 더 할애한다.'
를 위해 글의 아키텍처를 설계하는 과정을 거칩니다.
계획된 글쓰기는 잘 짜인 글이 되고, 잘 짜인 글은 이해를 쉽게 하고 읽는 시간을 줄입니다.
1️⃣ 글의 주제 선정
가장 처음으로는 어떤 글을 쓰는지 주제를 명확히 합니다. 목표로 하는 글은 시나 산문이 아닌, 정보를 전달하는 것을 목적으로 합니다.
어떤 주제를
왜 작성하는지
어떻게 설명할지
정리하면 됩니다.
Example
이 글의 주제는 테크니컬 라이팅입니다. 좋은 정보를 많이 알고 있더라도, 이를 제대로 전달하지 못하면 작성자와 독자 모두 시간을 낭비하게 됩니다. 테크니컬 라이팅은 글의 전달력을 높입니다. 독자가 쉽게 받아들이고 정확하게 이해하도록 돕습니다. 이 테크니컬 라이팅을 소개하고 설명하고자 합니다.
2️⃣ 독자 파악
내가 작성하는 글을 읽을 독자가 누구인지를 파악해야 합니다.
초보자
동료
다른 직군
범용적
업무 보고
전달하고자 하는 내용이 아무리 좋은 내용이라도 독자에 맞는 내용 전달이 이루어지지 않으면
독자는 그 정보를 100% 수용하기 어렵습니다.
작성하려는 글의 설명 수준을 결정할 수 있도록 대상 독자를 선정하세요.
Example
이 글은 범용적인 대상에게 전달합니다. 기술문서뿐만 아니라 다양한 정보를 효과적으로 전달할 때 사용하는 스킬을 다룹니다.
그리고 독자가 이 글을 읽고 나서 어떤 정보를 습득해야 하는지도 함께 정리합니다.
이 정리가 목표가 되고, 목표는 곧 목차 구성이 됩니다.
Example
전달력을 높이는 글 작성법을 습득합니다.
3️⃣ 목차 구성
글의 주제를 선정하고 독자를 파악했다면 어떤 구조로 전달할지를 고민하게 됩니다.
이 때, 목차는 깔끔한 글을 위한 뼈대이므로, 글이 난잡하지 않고 일직선으로 뻗을 수 있게 구성해야 합니다.
아래 예시는 본 포스팅을 바탕으로 만든 목차입니다.
Example
[소개]
[테크니컬 라이팅이란?]
[테크니컬 라이팅의 대원칙]
[테크니컬 라이팅의 상세 원칙] 테크니컬 라이팅 - 쓰기 전 테크니컬 라이팅 - 쓰면서 테크니컬 라이팅 - 쓰고 나서
[부록]
또한, 정리된 목차에 어떤 내용을 작성할지 간략하게 코멘트를 작성하는 것도 좋습니다.
생각나는 내용을 간략하게 적어두면 글을 쓸 때에 도움이 됩니다.
Example
[소개] - 잘못된 의사전달을 시작으로 의사전달 중요성 - 이 발표자료의 주제가 무엇인지 - 왜 필요하고 어떻게 소개할지 정리
[테크니컬 라이팅의 상세 원칙] - n 가지 기본원칙 정리 테크니컬 라이팅 - 쓰기 전 - 주제 선정과 독자 파악에 대해 - 글의 구조화에 대하여
테크니컬 라이팅 - 쓰면서 ... 생략
테크니컬 라이팅 - 쓰고 나서 ... 생략
[부록]
2) 쓰면서
글 쓰기 전 문서의 전반적인 아키텍처를 설계했다면 이제 내용을 채워 넣습니다.
철근 위에 콘크리트를 타설하듯 목차 위에 글을 집필합니다.
자, 이제부터가 본격적인 테크니컬 라이팅에 해당합니다.
다양한 원칙들 중에서 제가 선택한 8가지만 소개하겠습니다.
1️⃣ 두괄식 구성을 사용한다.
결론을 스포한다.
결론 혹은 핵심을 먼저 작성한다.
두괄식 구성은 결론을 스포하는 것입니다. 전하려는 핵심을 독자에게 먼저 인지시키고, 이후에 보충 내용을 서술합니다.
독자는 결론을 인지하고 있기 때문에 뒤에 나올 내용을 이해하는 게 훨씬 쉽습니다. 문서 어디에도 스펙터클한 반전은 필요 없습니다.
핵심을 먼저 작성해주세요.
Example
Poor: 프로그램이 동적으로 메모리를 할당하다 보면 메모리 영역에는 필요 없는 영역이 생기게 된다. 이런 필요 없는 영역을 해제하는 기능을 Garbage collection이라고 하며 이는 메모리 관리 기법 중의 하나이다.
Good: garbage collection은 메모리 관리 기법 중의 하나이다. 프로그램이 동적으로 할당했던 메모리 영역 중에서 필요 없게 된 영역을 해제하는 기능이다.
2️⃣ 일관성을 유지한다.
표현은 획일화한다.
하나의 뜻에는 하나의 표현만 사용한다.
일관성 유지는 독자를 헷갈리지 않도록 하는 것이 목적입니다. 하나의 단어는 글 전체에서 하나의 표현으로 이루어져야 헷갈리지 않습니다.
Example
Poor: 고사양 게임을 하기 위해 고사양 본체가 필요하다. PC 정보를 파악하려면 CPU-Z, GPU-Z같은 컴퓨터 정보를 볼 수 있는 시스템 소프트웨어 유틸을 사용하면 된다.
Good: 고사양 게임을 하기 위해 고사양 PC가 필요하다. PC 정보를 파악하려면 CPU-Z, GPU-Z같은 PC 정보를 볼 수 있는 시스템 소프트웨어 유틸을 사용하면 된다.
3️⃣ 간결한 문장을 사용한다.
문장의 호흡을 짧게 한다.
문장을 잇는 성분을 기준으로 분해한다.
긴 문장이 필요하면 쉼표를 사용한다.
미사여구, 형용사를 줄인다. (ex. 할 것이다 -> 한다 or 함)
하나의 문장이 길어지면 문장의 호흡이 길다라고 표현합니다. 독자는 긴 문장을 머릿속에서 다시 한번 분해해서 이해하는 과정이 필요합니다. 따라서 문장을 짧게 끊는 것이 좋습니다. 또한 미사여구나 형용사 사용을 줄여서 문장 자체를 간결하게 만드는 것도 좋습니다.
아래 예시는 극단적 표현을 위해 인위적으로 만들어졌기 때문에 어색이 내용이 있습니다.
호흡이 긴 문장이라는 부분에 집중해주세요.
Example
Poor: 개발자가 자주 사용하는 키보드는 기계식 키보드와 정전용량 방식의 무접점 키보드 2가지가 있다. 기계식 키보드는 브랜드 선정에 앞서 축을 선택하고 브랜드를 고르게 되는데 대표적인 브랜드로는 필코나 레오폴드, 바밀로 같은 키보드 브랜드가 있지만 그 외에도 매우 다양한 브랜드가 있어서 기계식 키보드를 선택한다면 개발자의 선택폭이 넓어지게 된다. 정전용량 방식의 무접점 키보드는 리얼포스나 해피해킹에서 선택하는 편이고 해피해킹의 키보드 배열은 조금 복잡한 편이라 호불호가 있다. 리얼포스 키보드에도 라인업이 여러 가지로 나뉘는데 키압에 따라서 나누거나 저소음인지 여부에 따라 나누는 방식이 있고 둘을 합친 방식도 존재한다.
Good: 개발자가 선호하는 키보드는 기계식 키보드, 정전용량 방식의 무접점 키보드 2가지가 있다. 기계식 키보드를 구매할 때는 브랜드보다 스위치 축을 먼저 선택해야 한다. ↵ 축을 선택했다면, 브랜드를 선정한다. ↵ 필코, 레오폴드, 바밀로 같은 브랜드가 대표적이다. ↵ 그 외에도 매우 다양한 브랜드가 존재한다. 정전용량 방식의 무접점 키보드를 구매할 때는 리얼포스나 해피해킹을 선택하게 된다. ↵ 리얼포스의 라인업은 키압, 소음 여부에 따라 분류한다. ↵ 해피해킹은 키보드 배열이 특이하여 호불호가 있다.
4️⃣ 목록과 순서를 사용한다.
두괄식 구성과 더불어 사용하면 뛰어난 효과를 볼 수 있다.
순서가 중요한 경우에는 '순서', 아닌 경우는 '목록'
정보를 전달하는 글에서 하나의 긴 문단보다는 개조식 표현이 깔끔합니다.
'간결한 문장을 사용한다'에서 수정한 내용은 수정전보다 간결해졌습니다.
하지만 여전히 문단은 길게 늘어져 있습니다. 어려운 내용이 아닌데 문장이 많아서 복잡하게 보입니다.
그래서 내용을 더 줄일 수 있도록 목록과 순서를 사용하도록 수정했습니다.
Example
Good: 개발자가 선호하는 키보드는 기계식 키보드, 정전용량 방식의 무접점 키보드 2가지가 있다. 기계식 키보드를 구매할 때는 브랜드보다 스위치 축을 먼저 선택해야 한다. 축을 선택했다면, 브랜드를 선정한다. 필코, 레오폴드, 바밀로 같은 브랜드가 대표적이다. 그 외에도 매우 다양한 브랜드가 존재한다.
정전용량 방식의 무접점 키보드를 구매할 때는 리얼포스나 해피해킹을 선택하게 된다. 리얼포스의 라인업은 키압, 소음 여부에 따라 분류한다. 해피해킹은 키보드 배열이 특이하여 호불호가 있다.
Best: 개발자가 선호하는 키보드에는 2가지 입력방식이 있다. - 기계식(설명 or link) - 축 선택이 중요함 - 정전용량 방식(설명 or link) - 보글거리는 느낌이 남
다음은 위 입력방식에 따라 선호되는 키보드 브랜드이다. - 기계식 - 레오폴드, - 필코 - 바밀로 - 키크론 - 그 외 다양
영문 문장 표현에서는 수동태 표현이 자연스럽지만, 한국어 문장은 수동태로 표현하면 번역체처럼 느껴질 수 있습니다.
Example
Poor: 로그인이 되어야 설정 페이지로 이동될 수 있다.
Good: 로그인을 해야 설정 페이지로 이동할 수 있다.
6️⃣ 긍정형 문장 사용한다.
인간의 뇌는 부정을 개념을 모른다.
부정형 -> 긍정형, 이중부정 == 긍정.
해석 시, 연산을 줄인다.
인간의 뇌는 부정의 개념을 이해하지 못합니다.
하지 말라고 하면 오히려 강조하는 효과가 됩니다.
따라서 긍정문으로 바꾸어 표현하는 것이 더 전달력이 좋습니다.
Example
Poor: 대상이 아닌 유저에게 보상을 지급하지 않습니다.
Good: 대상인 유저에게만 보상을 지급합니다.
// 간결한 표현 + 능동형 + 긍정형 문장으로 수정 Poor: 유틸성 로직은 추출되어 유틸 클래스로 만드는 것이 비즈니스 로직을 만드는 데에 방해가 되지 않는다.
Good: 유틸 클래스로 추출하는 것이 비즈니스 로직에 집중할 수 있다
7️⃣ 명확한 표현을 사용한다.
생략은 문단 흐름에 방해가 된다.
글에서는 설명했던 개념, 특정 대상, 행위 등을 치환하거나 생략하면, 누가 누구에게 어떤 행위를 하는지를 헷갈리게 됩니다.
일상에서는 대명사를 남용해도 거리낌이 크게 없지만, 글에서는 대명사를 자주 사용하는 것이 이해를 어렵게 만듭니다.
독자는 수정전의 문장을 읽을 때 대명사가 가리키는 것을 찾기 위해 문단의 처음, 혹은 이전 문단으로 돌아가야만 합니다.
Example
// 이해에 있어 불 필요한 콜스택 유발 Poor: a는 b와 비슷한 개념입니다. 그것은 c 와도 비슷합니다. 하지만 유사도로 치면 이전과 더 비슷합니다.
Good: a는 b와 비슷합니다. a는 c 와도 비슷합니다. 하지만 유사도로 치면 a는 b와 더 비슷합니다.
8️⃣ 시각적 요소를 적극 활용한다.
시각적 요소 '도표, 그림'
순서에 대한 정보
수치 위주의 내용
이미징이 필요한 내용
글을 잘 정리하면 시각적 요소는 생략이 가능합니다.
그럼에도 대부분의 기술문서나 정보전달 글에는 시각적 요소를 사용하는 것이 좋습니다.
글 내용에 순서 정보, 수치 데이터, 이미징이 필요한 케이스가 많기 때문입니다.
아래 예시는 Batch job들의 의존관계를 줄글에서 플로우 차트로 수정하였습니다.
Example
Poor: Job A의 수행이 끝나면 Job B 가 수행됩니다. Job B의 결과에 따라서 성공하면 Job C , 실패하면 Job D를 수행합니다. 또한 Job B 수행 이후에 Job E, F을 수행합니다. Job E, F의 결과와 Job C or D의 결과가 모두 성공하면 최종 성공, 하나라도 실패하면 최종 실패 상태가 됩니다.
Good:
3) 쓰고 나서
본문을 모두 작성했다면 최종 검토를 진행합니다.
필자는 글을 작성하는 동안 본문에 익숙해져 있습니다.
따라서 잘못된 부분을 인지하기 어렵습니다.
그래서 검토 단계가 필요합니다.
검토할 때에는
쓰기 전 단계에서 고려한 사항들
테크니컬 라이팅의 원칙이 잘 적용되었는지
를 확인합니다.
1️⃣ 목차에 맞게 적절하게 쓰였는가?
서론
왜 이글이 작성되었는지
어떤 내용을 작성할 지에 대한 설명이 충분한지
본론
하위 목차(대제목, 중제 목, 소제목)에 맞게 작성되었는지
문단의 내용이 하위 목차에 걸맞은 내용인지
흐름, 맥락을 방해하는 내용이 없는지
결론
서론과 본론의 조합 -> 결론 도출
결론만 보고도 맥락을 이해할 수 있는지
서론, 본론, 결론 각각에서 위 사항들을 고려하였을 때 적절하게 작성되었는지 확인하고 수정합니다.
2️⃣ 용어나 표현의 일관성이 유지되었는가?
너무나 당연한 사항입니다.
4.2.2에서 설명해드린 용어 표현의 일관성을 다시 한번 검토합니다.
3️⃣ 잘못된 or 필요 없는 표현이 수정되었는가?
오타를 수정하자. But, 수정에 대한 강박은 X
전반적인 흐름에 더 집중하자.
잘못된 표현을 수정하는 것 또한 당연한 사항입니다.
그런데 오타만 잘못된 표현이 아니라, 문단의 흐름에 맞지 않는 문장 또한 잘못된 표현입니다.
설명이 부족한 것은 이해가 덜 되겠지만, 흐름이 이상한 것은 이해를 어렵게 만듭니다.
또한, 특정 문장이 없더라도 내용을 이해할 수 있다면 제거합니다. 코드에서도 사용하지 않는 변수나 함수를 제거하는 것처럼 동일합니다.
4️⃣ 해설이 필요한 용어, 약어에 대해 정리가 되었는가?
낯선, 처음 등장하는 용어를 정리한다.
불필요한 약어를 줄인다.
너무 다양한 용어, 약어가 난무한 건 아닌지, 약어를 사용할 때는 충분히 설명하였는지를 확인합니다.
[Other Web vitals] - TTFB (Time To First Byte) - 설명... ...
5️⃣ 구두로 읽어 보기
눈으로 발견하지 못한 실수 잡기.
마지막으로 검토 방법은 바로 구두로 읽어보는 것입니다.
눈으로 읽을 때 자연스럽던 문장이 구두로 읽었을 때 어색할 수 있습니다. 이렇듯 문장의 흐름이나 문장 성분의 호응이 어색한 것들을 수정하면 됩니다.
또한, 읽으면서 숨이 차는 문장은 호흡이 긴 문장입니다. 간결한 문장의 원칙으로 수정하면 됩니다.
4) 정리
이렇게 해서 글쓰기의 한 사이클이 끝났습니다.
처음에는 너무 많아 보였지만, 막상 설명을 보면 우리가 일상에서 많이 사용해봤던 방법들이라고 여겨질 것 입니다.
이제부터 이 원칙들을 각 잡고, 실제 글쓰기에 적용해보세요.
여러분들의 글이 다른 독자를 위한 이상적인 글로 재탄생하게 될 것입니다.
다시 한 번 복기할 수 있도록 상체 원칙을 정리한 표
📝 부록
테크니컬 라이팅 원칙은 아니지만, 알아두면 좋은 팁을 추가로 남깁니다.
1. 어제의 코드가 Legacy가 되듯이, 어제의 문서도 Legacy가 된다.
✔️ 내용에 변화가 있다면 문서 갱신
2. 문서의 마이크로 서비스화
✔️한 문서에 모든 걸 담지 말자
3. 레퍼런스 주소는 꼭 대체 텍스트(alternative text)를 같이!
✔️링크가 깨졌을 경우 대체 검색어 제공 용도
4. 올바른 조사 사용하기(특히 영어)
✔️영어 단어 뒤에는, 읽을 때 자연스러운 조사 사용
✔️괄호 뒤에는 괄호 이전 단어에 맞는 조사 사용
5. 괄호 앞 띄어쓰기 규칙
✔️English (띄어 씀)
✔️국문(붙여 씀)
이상 'Technical Writing: 글로 하는 의사소통' 포스팅을 마치겠습니다.
여러분들의 글쓰기에 도움이 되셨길 바랍니다.
감사합니다.
참고문헌
1) 최재천, 『인간과 동물』, 라이언출판사, 2016년, p.128. 2) P.D. Miller, They Cried to the Lord: The Form and Theology of Biblical Prayer (Minneapolis: Fortress Press, 1994), p. 295. 3) 장 폴 샤르트르, 『지식을 위한 변명』, 조연훈 옮김, 한마당, 1999년, p.72 4) 라이언, 『취업보다 논문에 스트레스를 받는 사람들의 정신분석연구』, 취업대학교, 석사학위논문, 2016, p.128 5) 라이언, 『취업보다 논문에 스트레스를 받는 사람들의 정신분석연구』, 취준생 연구, 잡코리아연구, 19(7), 2016, p.271 6) 라이언,『라이언사전』 - '취업', 라이언출판사, 2016 7) 카카오, '논문', 2019년 6월 22일, http://www.kakaocorp.com 8) 김이언, '논문과 사랑에 빠진 A양', 카카오 일보, 2016년 6월 22일, 1면
