글 잘 쓰고 싶은 LINE 개발자를 위한 행사, ‘Technical Writing Day’에 다녀왔습니다

안녕하세요. 이번 글에서는 지난 11월 8일, 라인오피스에서 열렸던 ‘Technical Writing Day’에 대해 이야기해볼까 합니다.

이번 행사는 LINE 임직원들에게 테크니컬 라이팅에 대해 알리고자 LINE Technical Writing 팀에서 개최한 사내행사였습니다. 테크니컬 라이팅에 대한 소개와 함께, 논리적인 문서 구조를 만드는 방법과 바른 문장을 쓰는 방법, 한국어로 기술 문서를 작성하면서 국제화를 고려하는 방법, API 문서를 PDF나 웹페이지 등으로 만드는 방법 등 문서 작업 전반에 도움이 되는 여러 가지 방법과 노하우가 공유된 알찬 행사였다고 합니다. 그럼 각 세션에서 어떤 내용이 전달되었는지 사진과 함께 보시겠습니다.

행사 소개

행사는 총 6개의 세션이 회의실 세 곳에서 병렬로 진행되었습니다. 회의실 두 곳에선 교육이 진행되었고요. 나머지 한 곳에선 문서 컨설팅과 wiki Q&A가 진행되었습니다. 교육은 현재 LINE에서 테크니컬 라이터로 일하고 있는 분들이 강사를 맡아 진행하였는데요. 바쁜 일정 속에서도 유연하게 챙겨들을 수 있도록 오전과 오후에 동일한 내용이 반복 진행되었던 점이 독특했습니다.

그럼 각 세션에서 어떤 내용을 소개했는지 살펴보겠습니다.

‘Introduction to Technical Writing’ by 이인실 님

환영 인사와 함께 시작한 이인실 님은, 테크니컬 라이터를 ‘개발자와 개발자 간의 정보를 연결해주는 역할을 하는 사람’이라고 정의하였습니다. 그리고 각 단계별로 어떤 문서를 언제 작성하기 시작하고 언제 릴리스하는지 좀 더 쉽게 이해할 수 있도록 소프트웨어 문서 매트릭스를 이용해 설명했고, 현재 LINE에서 Technical Writing 팀이 하고 있는 일들도 소개하였습니다. 마지막으로 이후 진행될 세션들을 간략하게 소개하며 마무리하였습니다.

‘Logical Writing’ by 김지현 님

이번 세션에선 재미있는 실습과 함께 논리적인 문서 구조를 만드는 방법에 대해 배울 수 있었는데요. 김지현 님은 테크니컬 라이팅을 ‘특정 독자에게 특정 목적을 가지고 특정 정보를 전달하는 글쓰기’라고 정의한 뒤, 글쓰기가 쉬워지는 P.O.W.E.R. Writing을 소개하였습니다. Preparing, Organizing, Writing, Editing, Reviewing으로 구성되어 있었는데요. 이번 세션에선 그 중에서 Preparing과 Organizing, 두 가지를 다뤘습니다.

Preparing에선 문서를 쓰기 전에 주제, 독자, 개요, 이 3가지를 고민해야 한다고 했는데요. 특히, 독자의 지식 수준과 독자가 원하는 정보, 즉 목적에 대해 확인해야 한다고 말했습니다. 그리고 이어진 Organizing에선 문서의 구조를 잡는 방법에 대해 알아보았는데요. 문서 구조 잡기는 글감을 정리하고, 목차를 만드는 순서로 구성되어 있었습니다. 글감 정리하기에선 영국의 교육심리학자 토니 부잔이 개발한 마인드맵을 소개받고 실습도 해볼 수 있었고요. 목차 만들기에선 피라미드 구조에 대해 설명을 듣고, 마인드맵 실습 결과에 Why so/So what과 MECE(Mutually Exclusive Collectively Exhaustive, 겹치거나 빠짐이 없음)의 원칙을 적용해 논리적인 오류가 없는지 검토해보는 실습을 해볼 수 있었습니다.

‘Technical Editing’ by 김지현 님

이번 세션도 Logical Writing 세션에 이어 김지현 님이 진행했는데요. Logical Writing 세션에서 소개되었던 P.O.W.E.R. Writing의 나머지 3가지인 Writing, Editing, Reviewing에 대한 내용으로 채워져 있었습니다. 
Writing에선 글쓰기 준비에서 정리한 내용을 ‘그저 펜 가는 대로’ 글로 표현하고, 초고와 퇴고의 과정을 구분하라고 이야기하였습니다. 그 다음 Editing에선 정확성, 일관성, 간결성, 보편성이라는 4가지 기본 원칙을 염두에 두라고 했는데요. 정확성은 정확한 정보를 문법에 맞게 쓰는 것이고, 일관성은 용어, 표현, 어투를 일관되게 쓰는 것을 의미한다고 했습니다. 간결성은 짧고 분명하게 쓰는 것이고, 보편성은 누구나 알 수 있게 쓰는 것을 말한다고 했습니다. 이 4가지 원칙을 가지고 우리가 평소에 자주 접할 수 있었던 예시를 살펴보고, 실제로 문장을 고쳐보는 실습도 해보았습니다. 마지막 Reviewing에선 스스로 검토하고, 체크리스트를 확인하고, 동료 검토를 거치라고 설명했는데요. 마지막 동료 검토 시 검토자와 작성자의 태도가 중요하다고 이야기했습니다.

‘디벨로퍼 션샤인 따라잡기’ by 황수정 님

황수정 님은 최근 인기리에 종영된 드라마 ‘미스터 션샤인’을 모티브로 세션의 이름을 지었다고 말했습니다. 황수정 님은 한국어, 영어, 일본어까지 모두 잘했던 유진초이를 언급하며, 글로벌 기업 LINE에선 기술문서를 작성할 때 국제화를 염두에 두어야 할 때가 많다고 이야기하였습니다. 그래서 어떻게 하면 국제화가 잘 되도록 한국어로 기술 문서를 작성할 수 있는지, 그 방법을 정확성, 간결성, 어휘/표현 적합성, 존재성, 일관성, 문장 구성, 그리고 마지막 정성으로 이루어진 7가지 특성으로 나누어 설명했습니다.

각 특성을 짧게 요약해 드리면, 정확성은 내가 작성한 문장이 내가 전달하고자 하는 정보를 100% 그대로 전달하고 있는지, 의미가 왜곡되지는 않았는지를 생각해 보는 것이고요. 간결성은 문장이 한번에 이해가 되는지, 문장을 이해하기 위해 독자가 문장을 여러 번 읽어야 하는지를 확인해 보는 것입니다. 어휘/표현 적합성은 내가 사용한 단어가 적합한지, 다르게 해석될 여지는 없는지에 관한 것이고, 존재성은 누락된 정보는 없는지, 중복된 정보는 없는지, 나만 이해하는 정보가 있지는 아니한지 생각해 보는 것이었습니다. 일관성은 단어가 일관성 있게 쓰여지고 있는지 확인하는 것이고요. 문장 구성은 수식어의 위치를 확인해보는 것입니다. 마지막으로 정성은 말 그대로 정성을 들여서 위에서 다룬 여섯 가지 특성이 문서에 잘 고려되었는지 확인하고, 끝까지 독자의 입장에서 독자에게 집착하여 문서를 작성하는 것을 말한다고 했습니다. 

이렇게 7가지 특성을 각 특성별로 실제 LINE에서 작성된 문서에서 찾은 사례와 함께 배워볼 수 있어서 더욱 쉽고 확실하게 이해할 수 있는 시간이었습니다. 

‘API document engineering’ by 전정은 님

이번 세션은 문서 엔지니어링 방법에 초점이 맞춰져 있었습니다. 전정은 님은 문서화 프로세스에 대해 먼저 설명한 뒤, 실제 자주 일어날 법한 3가지 상황을 예시로 들고 각 상황에서 어떻게 대처하면 되는지 설명했습니다. 첫 번째로 Javadoc을 PDF로 만들고 싶은 상황인데요. 이 상황에서는 Doxygen으로 빌드한 뒤 LaTeX 템플릿을 적용하라고 설명했고요. 두 번째로 위키 페이지를 PDF로 내보냈는데 문서에서 깨지는 현상이 발생했을 때는 위키 페이지를 우선 HTML로 내보내기 한 뒤, HTML을 markdown으로 변환하고(confluence-to-markdown), 다시 markdown을 PDF로 변환(Pandoc 등)하면 된다고 설명하였습니다. 마지막으로 Swagger로 작성한 것을 PDF로 만들어야 할 때가 있는데요. 이럴 때는 Swagger를 markdown으로 변환(swagger2markup)한 뒤, markdown을 PDF로 변환(Pandoc 등)하면 된다고 설명하였습니다.

‘Document consulting & Wiki Q&A’

강의 세션이 진행되는 동안, 별도로 마련된 회의실에선 document consulting과 wiki Q&A가 진행되었습니다. 평소 문서 작업 중, 혹은 wiki를 사용하다가 궁금하거나 어려운 점이 있으셨다면, 자유롭게, 부담없이 찾아와서 상담하고 물어볼 수 있는 자리였는데요. 이 자리에서 문서 작업에 대한 상담을 받다가 Technical Writing 팀과 새롭게 문서 프로젝트를 시작하게 된 사례도 나왔다고 합니다.

마치며

이번 글에선 LINE에서 열린 사내행사, ‘Technical Writing Day’에 대해 나눠보았습니다. 개발자들은 개발 뿐 아니라 글을 써야하는 경우도 많이 접하게 되는데요. 특히 개발환경이 점점 더 글로벌해지면서 모국어 외의 언어로 기술 문서 등을 써야 하는 경우가 많이 발생하고 있습니다. 그럴 때 이런 행사에서 접한 내용들이 정말 많은 도움이 될 것 같습니다. LINE은 참 여러 가지 측면에서 개발자들의 실력을 배양해주고 있다는 것을 알게 되었는데요. 앞으로 또 멋진 행사가 열리길 기대하며 이만 마치겠습니다.