if(kakao)2022 의 '테크니컬 라이팅: 글로 하는 의사소통' 세션을 글로 옮긴 것이다. 좋은 글쓰기가 왜 늘 후순위로 밀리는지 짚은 뒤, 쓰기 전·쓰면서·쓰고 나서 세 단계로 나눈 원칙을 Poor/Good 예시와 함께 제시한다. 발표자는 자기 소개글부터 나쁜 예로 내놓고 직접 고쳐 보이며 시작한다.
핵심 포인트- 대원칙 둘: 내가 하고 싶은 말이 아니라 상대가 알아야 할 내용을 쉽게 쓴다, 독자 n명의 시간 대신 나 한 사람의 시간을 더 쓴다.
- 쓰기 전에는 주제 선정, 독자 파악, 목차 구성으로 글의 아키텍처를 먼저 설계한다.
- 쓰면서 지킬 원칙 8가지는 두괄식, 일관성, 간결한 문장, 목록과 순서, 능동형, 긍정형, 명확한 표현, 시각적 요소다.
- 쓰고 나서는 목차 부합·용어 일관성·불필요한 표현·약어 정리·구두로 읽어 보기 5가지로 검토한다.
- 테크니컬 라이팅을 안 하는 이유가 "잘 모른다·바쁘다·귀찮다" 라는 점에서 테스트 코드와 똑같다고 비유한다.
상세 정리- 도입 실연: 발표자가 자기 소개글을 그대로 보여준 뒤 "두세 번 읽어야 주제를 알 수 있다" 고 지적하고, 같은 내용을 결론 먼저 오는 문장으로 다시 써서 차이를 보여준다.
- 필요성: 아무리 많은 정보를 알아도 전달 방식에 따라 독자에게 도달하는 양이 제한된다는 것을 벤 다이어그램으로 설명한다.
- 주제 선정: 정보 전달이 목적인 글이므로 어떤 주제를, 왜 쓰는지, 어떻게 설명할지를 먼저 정리한다.
- 독자 파악: 초보자·동료·다른 직군·범용·업무 보고 중 누구를 대상으로 하는지에 따라 설명 수준이 달라진다. 독자가 무엇을 얻어 가야 하는지를 정리하면 그것이 곧 목차가 된다.
- 목차 구성: 목차는 글이 일직선으로 뻗게 하는 뼈대이며, 각 항목 아래 어떤 내용을 쓸지 짧은 코멘트를 미리 달아두면 집필이 쉬워진다.
- 원칙 ① 두괄식: 문서에 반전은 필요 없다. Garbage collection 설명을 예로 들어 정의를 먼저 놓고 부연을 뒤에 두는 쪽이 이해가 빠름을 보인다.
- 원칙 ② 일관성: '본체·PC·컴퓨터' 를 섞어 쓰지 말고 하나의 뜻에는 하나의 표현만 쓴다.
- 원칙 ③ 간결한 문장: 문장을 잇는 성분에서 끊고, 미사여구·형용사를 줄이며(할 것이다 → 한다), 길어야 할 때는 쉼표를 쓴다. 키보드 설명 문단을 길게/짧게 두 버전으로 비교한다.
- 원칙 ④ 목록과 순서: 짧게 고친 문단도 여전히 길어 보이면 개조식으로 바꾼다. 순서가 중요하면 번호 목록, 아니면 불릿을 쓴다.
- 원칙 ⑤ 능동형: 한국어에서 수동태는 번역체로 읽힌다. "로그인이 되어야 이동될 수 있다" 를 "로그인을 해야 이동할 수 있다" 로 고친다.
- 원칙 ⑥ 긍정형: 부정문은 오히려 그 내용을 강조하는 효과가 난다. "대상이 아닌 유저에게 지급하지 않습니다" 를 "대상인 유저에게만 지급합니다" 로 바꾼다.
- 원칙 ⑦ 명확한 표현: 대명사는 독자가 앞 문단으로 되돌아가게 만든다. "그것은 c 와도 비슷합니다" 대신 주어를 반복해 쓴다.
- 원칙 ⑧ 시각적 요소: 순서 정보, 수치 데이터, 이미지가 필요한 내용은 도표·그림으로 옮긴다. 배치 잡의 선후 관계를 글로 늘어놓은 예를 다이어그램으로 대체해 보인다.
- 검토 단계: 서론이 왜 쓰는지 설명하는지, 본론이 하위 목차에 맞는지, 결론만 보고 맥락이 잡히는지를 확인한다. 오타 강박보다 흐름을 본다. 없어도 이해되는 문장은 쓰지 않는 변수를 지우듯 제거한다.
- 용어 정리: 처음 등장하는 용어와 약어를 모아 용어집을 만든다. Core Web Vitals 의 LCP·FID·CLS 를 예로 든다.
- 마지막 검토는 소리 내어 읽기다. 눈으로는 자연스럽던 문장의 호응 오류가 드러나고, 읽다 숨이 차면 문장이 긴 것이다.
- 부록 팁: 어제의 코드가 레거시이듯 문서도 레거시가 되니 갱신할 것, 한 문서에 다 담지 말고 쪼갤 것, 링크에는 대체 텍스트를 붙일 것, 영문 뒤 조사와 괄호 앞 띄어쓰기 규칙을 지킬 것.
왜 읽나설계 문서·회고·PR 설명을 쓸 때마다 막히는 개발자에게 바로 적용할 원칙과 고치기 전후 예시를 한 번에 준다.
카카오 엔터테인먼트 FE·
NHN Cloud·
Stack Overflow Blog·
포스타입·