테크니컬 라이팅을 잘 하려면 기대치를 낮춰야 합니다 [번역글]
(blogbyash.com)-
글쓰기는 엔지니어의 필수 역량
- 기술 글쓰기는 커밋 메시지부터 문서화까지 모든 레벨의 엔지니어에게 필수적입니다.
- 글을 잘 쓰는 것과 그렇지 않은 것의 차이는 업무 효율과 조직 커뮤니케이션에 큰 영향을 미칩니다.
-
최대한 간결하게, 짧게
- 독자는 글에 많은 시간을 들이지 않습니다.
- 아이디어를 한 문장으로 전달할 수 있다면 그렇게 하세요.
- 세부사항을 일부러 생략하는 게 오히려 장점입니다.
- 중요한 내용은 글의 앞부분, 첫 문장이나 제목에 담으세요.
-
기대치를 현실적으로 설정
- 기술 글을 꼼꼼히 읽고 완전히 이해할 것이라 기대하지 마세요.
- 엔지니어링 조직에서 혼란과 이해도 차이는 정상적이며, 글쓰기로 모두를 같게 만들 수 없습니다.
- 기대치를 낮추면 오히려 효과적인 커뮤니케이션이 됩니다.
-
글의 목적은 명확한 핵심 전달
- “설정 추가는 복잡하다”와 같이 매우 단순한 요점을 넓은 팀에 전달하는 것이 최우선 목표입니다.
- 기술적으로 완전한 이해를 이끌어내는 것보다, 최소한의 컨텍스트를 제공해 신뢰를 주는 게 중요합니다.
-
실제로 기대할 수 있는 효과
- 글의 수신자는 대체로 작성자보다 배경지식이 부족합니다.
- 넓은 대상에게는 단순 메시지 전달, 극소수에게는 복잡한 내용의 명확한 전달이 가능합니다.
- 핵심만 짚어주는 것만으로도 대규모 조직에서 큰 차이를 만듭니다.
-
명확한 사고가 명확한 글을 만든다
- 이해가 불충분한 주제는 압축이 어렵습니다.
- 불확실성을 인정하고, 명확히 설명할 수 있는 부분에 집중하세요.
-
실수 및 권장점
- 너무 많은 세부 정보 전달에 집착하지 마세요.
- 전달하려는 내용은 한 문장, 한 단락, 한 페이지 단위로 점점 축약해서 핵심을 먼저 전달하세요.
- 기술적 배경지식이 거의 없는 이들에게도 큰 맥락을 전달하는 것 자체가 가치 있습니다.