[TW] 기술문서의 쉼표 사용 가이드라인

시작하며 안녕하세요. 테크니컬라이팅 팀의 Crystal(김유리)과 Sandy(차신영)입니다. 쉼표는 글을 쓰고 읽는 사람 모두에게 친숙한 문장 부호인데요. 일상생활에서 '오늘의 쉼표'와 같은 관용 표현으로도 자주 사용되어 우리에게 친숙한 문장 부호이기도 합니다. 우리가 이메일을 쓰거나 문서를 작성할 때도 습관적으로 쉼표를 많이 사용하게 되는데요. 주로 긴 호흡의 문장에서 끊어 읽기를 하거나 단어 등을 열거할 때 쉼표를 사용하는 경향이 있습니다. 이렇게 매일 사용하고 있는 쉼표를 과연 제대로 사용하고 있을까요? 테크니컬라이팅 팀에서는 얼마 전 잘못된 쉼표 사용이나 무분별한 쉼표 사용 등을 주제로 논의를 했었는데요. 실제 저희가 작성한 기술문서를 분석해보니 작성자에 따라 쉼표 사용이 제각각이라는 것을 알 수..

[TW] Release Note 톺아보기

시작하며 안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리)과 Sandy(차신영)입니다. 지금까지 테크니컬라이팅 팀에서는 테크니컬라이팅 관련 포스팅을 기고하고 있는데요. 이번 포스팅을 시작으로 다양한 기술문서에 대해 상세히 알아보는 톺아보기 시리즈를 새롭게 선보이게 되었습니다. 제목에 있는 “톺아보기”라는 단어를 보시고, 생소하기도 하고 오타는 아닐까 하는 의심이 드신 분들도 계셨을 텐데요. 우리말샘 사전에 따르면 “톺아보기”는 ‘샅샅이 톺아 나가면서 살피다’라고 명시가 되어있습니다. ‘틈이 있는 곳마다 모조리 더듬어 뒤지면서 찾다’라는 뜻의 ‘톺다’와 ‘보다’가 합쳐진 순우리말인데요. 기존 테크니컬라이팅 시리즈에서 테크니컬 라이터로서 글쓰기 팁과 노하우를 소개해드렸다면, 톺아보기 ..

[TW] 개요 작성의 중요성

시작하며 안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리)과 Sandy(차신영)입니다. 이전 포스팅에서 목차의 중요성과 기술 문서 작성 5단계 등 테크니컬라이팅 기법을 설명드렸는데요. 오늘은 그 연장선으로 기술문서 본문 첫 페이지에 등장하는 개요에 대해 살펴보고, 개요의 역할과 작성 방법 등을 알아보겠습니다. 누군가를 처음 만날 때 듣게 되는 자기소개처럼 기술문서의 도입부에 위치한 ‘개요’는 해당 문서를 처음 펼쳐본 독자에게 전하는 문서의 자기소개라고 할 수 있습니다. 즉, 개요를 통해 독자는 해당 문서가 어떤 내용인지 대략적으로 파악할 수 있는데요. 훌륭한 1분의 자기소개가 면접의 당락을 가를 수 있듯이, 잘 정돈된 개요는 독자와 마주한 문서의 첫인상을 결정하는 동시에 해당 문서..

[TW] 개발자들을 위한 테크니컬 라이팅 10계명

시작하며 안녕하세요. 카카오엔터프라이즈 테크니컬라이팅팀의 Crystal(김유리)과 Sandy(차신영)입니다. 그 동안 테크니컬라이팅 팀에서는 테크니컬 라이팅 4대 원칙과 언어학 관점에서 기술문서 가독성 향상 전략 등 테크니컬 라이팅과 관련한 정석적인 주제를 다뤘었는데요. 며칠 전 개발자 한 분께서 "테크니컬 라이팅 교육을 받고 싶은데 시간은 없고.. 어떻게 하면 기술 문서를 잘 쓸 수 있을까요? 혹시 간단한 팁이 있을까요?" 라는 질문을 주셨습니다. 생각해보면 개발자들이 많은 시간을 들여 테크니컬 라이팅을 심도있게 공부하기는 현실상 쉽지 않은 게 사실인데요. 그래서 오늘은 수 많은 테크니컬 라이팅의 이론과 팁 중에서도 기술문서 작성에 관심이 있으신 개발자 분들이라면 꼭 알아야 할 10가지 팁을 간추려 소..

[TW] 목차의 중요성

시작하며 안녕하세요. 카카오엔터프라이즈 테크니컬라이팅팀의 Crystal(김유리)과 Sandy(차신영)입니다. 이번 테크니컬 라이팅 포스팅에서는 목차(Table of Contents)라는 주제를 다뤄보려고 합니다. 얼마 전에 저희 테크니컬라이팅팀에서 “기술 문서 작업 단계에서 가장 중요한 하나를 꼽는다면?” 이라는 질문에 대해 의견을 나눈 적이 있었는데요. 저희 모두 목차 구성으로 의견 일치를 본 만큼, 테크니컬 라이팅 기법에서 목차는 정말 중요한 주제가 아닐 수 없습니다. 본론으로 들어가기 전에 여러분이 지금 서점에서 특정 주제에 대한 책을 구매하려 한다고 가정해 보겠습니다. 이 상황에서 여러분들은 책의 어떤 부분을 가장 먼저 살펴보시나요? 아마 대부분의 경우 “목차”일 것입니다. 해당 목차에서 특정 페..

[TW] 기술문서 쉽게 쓰기 지침

시작하며 안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리)과 Sandy(차신영)입니다. 오늘은 ‘기술문서 쉽게 쓰기 지침’이라는 주제로 포스팅을 해 보려고 하는데요. 먼저 기술문서의 한 단락을 살펴보도록 하겠습니다. 어떠신가요? 일단 ‘역시 기술문서라서 어렵네’라는 생각을 하시는 분들이 많으실 텐데요. 다행히도 위 문장은 이번 주제를 함축적으로 설명하기 위해 가상으로 작성해 본 예시입니다. 사실 한국어의 경우 과거부터 한자어를 다수 포함한 만연체 문장이 널리 쓰였고, 최근까지도 각종 문서에서 외국어 번역체가 무분별하게 사용되고 있는 현실에 비추어 볼 때, 한국어에는 아직도 비직관적인 언어 습관이 많이 쓰이고 있는 것 같습니다. 오히려 과거에는 만연체나 번역투 문장이 더 트렌디하게 ..