들어가며
안녕하세요. Technical Content Strategy 팀 손근입니다. 저희 팀은 지난 2월 22일 일본 Dev Content 팀과 함께 사내 임직원을 대상으로 'Technical Documentation Day'라는 온라인 행사를 개최했습니다. 이 행사는 재택 근무를 기반으로 끊임없이 글과 문서로 소통하는 저희 임직원이 보다 효율적으로 글과 문서를 작성하고 관리하며 협업할 수 있도록 여러 가지 팁과 스킬을 알려주는 행사였는데요. 상대방을 배려하는 Slack 메시지 작성 방법부터 기술 문서 작성 및 관리 방법의 새로운 패러다임인 DocOps를 소개하는 세션까지, 다양하고 폭넓은 주제로 알차게 준비된 Technical Documentation Day의 참석 후기를 공유하려고 합니다.
행사 소개
저희 팀에서는 이전에도 'Technical Writing Day'라는 이름으로 이와 같은 행사를 몇 차례 개최했습니다(참고). 코로나19 팬데믹 이전이었던 당시에는 한국와 일본, 태국, 대만의 오피스에 직접 찾아가 오프라인으로 행사를 진행했는데요. 회사 합병 후 다시 한번 모두에게 글쓰기와 문서 작성 및 관리와 관련해 여러 가지 유용한 정보를 전달하면 좋을 것 같아 이번 행사를 기획했습니다. 이번 행사는 이전과는 달리 다루는 주제를 테크니컬 라이팅뿐 아니라 문서화 전반으로 넓혔고, 이에 따라 행사 이름도 'Technical Writing Day'에서 'Technical Documentation Day'로 변경됐습니다.
저희 팀에서 이런 행사를 개최하는 이유는 크게 두 가지입니다. 하나는 앞서 말씀드렸듯 LY 임직원이 조금 더 효율적으로 글과 문서로 소통하고 협업할 수 있도록 여러 가지 문서 작성 관련 팁과 스킬, 노하우를 알려주기 위해서입니다. 또 하나는 팀 홍보인데요. 사내에 이와 같은 업무를 전문으로 담당하는 팀이 있으니 도움이 필요할 때 Technical Content Strategy 팀과 Dev Content 팀을 떠올릴 수 있도록 알리기 위해서입니다.
행사 준비 과정
행사 진행이 확정된 후 저희 팀과 일본 Dev Content 팀 내부에서 발표자를 모집했습니다. 그동안 공유하고 싶었던 게 많았던 여러 팀원들이 적극 나서 주셔서 총 9명의 발표자가 8개의 세션을 진행하는 것으로 결정됐습니다. 행사 일정은 많은 분들이 참석할 수 있도록 한국과 일본의 휴일 등을 고려해 2024년 2월 22일로 결정됐고, 여러 지역에서 주로 재택 근무로 일하고 계신 임직원을 고려해 Zoom 웨비나 형식으로 진행했는데요. 그럼 어떤 세션이 준비됐고 각 세션에서는 어떤 내용이 소개됐는지 살펴보겠습니다.
세션 소개
Technical Documentation Day는 오후 2시부터 5시 반까지 총 8개 세션이 진행됐습니다.
세션 시간 | 세션 명 | 발표자 |
---|---|---|
14:00-14:20 | 테크니컬 라이터가 하는 일 | 이인실 |
14:20-14:50 | Beyond Wiki: 좀 더 나은 방식으로 문서 제공하기 | 전정은 |
14:50-15:00 | 휴식 시간 | |
15:00-15:15 | Slack 메시지를 이해하기 쉽게 작성하는 방법 | Hiroki Zenigami |
15:20-15:40 | 문서 구조를 이해하는 한 가지 관점 | 박하늬 |
15:40-15:55 | 글쓰기의 안티 패턴 | Ryotaro Furuki |
15:55-16:00 | 휴식 시간 | |
16:00-16:30 | Words 100% 활용하기 | 최소영/김지현 |
16:30-16:50 | 의미 전달이 잘 되는 번역 팁 소개 | Kozue Takasaki |
16:50-17:00 | 휴식 시간 | |
17:00-17:30 | DocOps 인사이트 - 기술 문서 관리 경험 공유 | 강정일 |
각 세션의 내용을 간략히 소개하겠습니다.
테크니컬 라이터가 하는 일, 이인실 님
첫 번째 세션은 Technical Content Strategy 팀의 리드 인실 님이 맡아주셨습니다.
인실 님은 먼저 이 행사를 기획한 목적을 공유했는데요. 테크니컬 라이터가 하는 역할과 사내에 이런 전문가들이 모인 팀이 있다는 것을 널리 알려 도움이 필요한 임직원이 적시에 제대로 된 도움을 받을 수 있도록 하기 위한 것이라고 밝혔습니다. 이어서 테크니컬 라이팅의 정의를 소개했는데요. 위키백과의 Technical writing 페이지를 인용해 '테크니컬 라이팅이란 전문적인 환경에서 기술 문서를 작성하고 기술 정보를 공유하는 프로세스'라고 정의를 한 뒤, 테크니컬 라이터의 역할은 '가능한 한 명확하고 효율적인 방식으로 기술 정보를 다른 사람이나 조직에게 전달하는 것'이라고 말했습니다.
이어서 한국과 일본에서 각각 이와 같은 역할을 담당하고 있는 조직 및 각 조직의 산출물과 담당 업무가 소개됐습니다. LY의 테크니컬 라이터는 문서 작성과 관련해 여러 가지 일을 담당하고 있는데요. 먼저 이 글을 읽고 계신 기술 블로그 LY Tech Blog와, 사내 플랫폼과 도구의 진입점으로써 각 플랫폼과 도구를 간단히 설명하고 관련 링크를 안내하는 사내 웹사이트인 GO/Docs, 사내 용어 사전 Words, LINEヤフー의 광고 비즈니스 문서 등이 소개됐습니다. 이어서 저희 팀의 핵심 역할이라고 할 수 있는 플랫폼 문서화의 작업 결과가 소개됐는데요. 아래는 소개된 결과물 중 외부로 공개된 웹사이트만 추린 것입니다.
- LY Corporation Tech Blog(영어/한국어): https://techblog.lycorp.co.jp/en, https://techblog.lycorp.co.jp/ko
- LINE Developers: https://developers.line.biz
- LINE GAME Developers: https://developers.game.line.me
- LINE Blockchain Developers Docs: https://docs-blockchain.line.biz
- Finschia Docs: https://docs.finschia.io
- LINE Planet: https://docs.lineplanet.me
- Armeria Tutorials: https://armeria.dev/tutorials
- LINEヤフー for Business お知らせ(notice): https://www.lycbiz.com/jp/news/
- Global Marketing Solution information: https://global-marketing.yahoo.co.jp/information/
이외에도 사내 여러 플랫폼의 문서를 작성 및 관리하고 있으며, 사내 임직원을 대상으로 글쓰기 교육을 진행하고 있고, 테크니컬 라이팅 관련 외부 밋업을 운영하고 커뮤니티에 참여하는 등 외부 활동도 활발하게 이어나가고 있다고 전했습니다. 세션은 이후 어떤 세션이 준비돼 있는지 짤막하게 소개하는 것으로 마무리됐습니다.
Beyond Wiki: 좀 더 나은 방식으로 문서 제공하기, 전정은 님
다음으로 전정은 님의 세션이 진행됐습니다. 정은 님은 먼저 아이스브레이킹으로 사내에서 쓰고 있는 자신의 예명(Ragina)의 의미를 간단히 설명한 뒤 자신을 문서 엔지니어(document engineer) 및 테크니컬 라이터라고 소개했습니다.
테크니컬 라이터에 대해서는 앞서 인실 님 세션에서 간단히 살펴봤는데요. 문서 엔지니어가 무엇인지 궁금하신 분들은 정은 님이 준비한 아래 자료를 참고해 보시면 좋을 것 같습니다.
- 문서 엔지니어링과 API 문서화(LINE Engineering 블로그)
- 주석 분석기를 이용한 간단한 API 문서화 방법(LINE Engineering 블로그)
- 기술 문서 사이트로 Docusaurus 활용하기(LY Tech 블로그)
- 테크니컬 라이터에 관한 오해와 진실 | 라인개발실록(YouTube 라인개발실록)
소개를 마친 뒤 본격적으로 본론으로 들어갔습니다. 이번 세션에서 정은 님은 현재 LY에서 사내 문서 관리 도구로 사용하고 있는 Confluence의 특성을 살펴본 뒤 문서의 특성에 따라 Confluence가 아닌 더 나은 방식으로 제공할 수 있는 방법을 제안했습니다.
Confluence의 특성
LY에서는 위키 형식으로 문서를 관리할 수 있는 Atlassian사의 Confluence를 사내 문서 작성 및 공유 시스템으로 사용하고 있습니다. 정은 님은 Confluence는 분명 이전에 회사에서 문서를 작성하고 공유하던 방식(이메일이나 사내 메신저, 네트워크 드라이브)과는 비교할 수 없을 만큼 편리한 여러 가지 장점이 있다고 말했습니다. 여러 사용자가 동시에 문서를 편집하며 그 내용을 실시간으로 공유할 수 있고, 글자 하나 하나에 코멘트를 남길 수 있으며, 이력을 쉽고 편하게 관리할 수 있고, 따로 설치할 필요가 없이 관련 권한만 있다면 누구나 문서를 열람하거나 작성 및 수정해 공유할 수 있습니다.
이와 같은 여러 장점이 있는 Confluence지만 단점도 있다고 말했는데요. 첫 번째로 짚은 단점은 로컬 복사본이 없는 방식이라는 것입니다. Confluence은 웹 기반으로 로컬 복사본을 남기지 않기 때문에 시스템이 다운되거나 네트워크가 불안정할 때에는 문서를 작성하는 것도 열람하는 것도 불가능합니다. 단순히 문서를 작성해야 하는 순간 뿐 아니라 Confluence에 올려 놓은 문서에 적힌 정보를 기반으로 진행해야 하는 모든 업무가 멈출 수 있는 것이죠. 두 번째 단점은, 누구나 작성할 수 있기 때문에 자칫하면 여기 저기 같은 내용의 문서가 난립할 수 있고, 이렇게 난립한 문서들이 제대로 관리되지 않아 기한이 지나거나 잘못된 정보를 전달할 수 있다는 것입니다. 문서를 만들기가 너무 편하다는 그 특성상 일단 만들어 놓고 지우지 않는 경우가 많은 것이죠. 또한 검색 기능을 제공하고는 있지만 성능이 썩 좋지 않고, 수많은 임직원이 온갖 종류의 문서를 대량 생성하고 있어서 원하는 검색 결과를 쉽게 얻기도 어렵다고 밝혔습니다.
Confluence가 공식 문서 관리 도구로 적합하지 않은 이유
정은 님은 먼저 공식 문서란 꼭 외부용 문서만을 말하는 것이 아니며 팀이나 프로젝트에서 어떤 하나의 주제와 관련해 '이 문서가 관련 정보를 검증해서 작성해 놓은 유일한 공식 문서입니다'라고 말하는 모든 문서를 일컫는다고 정의한 뒤, 이와 같은 문서를 Confluence로 다룰 때의 단점으로 네 가지를 꼽았습니다.
먼저 고가용성입니다. 공식 문서는 관련된 사람들이 언제든 접근할 수 있어야 하는데, Confluence는 모든 문서가 모이는 곳이기에 만약 'A'와 관련된 콘텐츠 때문에 Confluence에 장애가 발생한다면 'A'와 전혀 상관 없는 'B' 공식 문서에도 접근할 수 없게 될 것이라고 했습니다.
두 번째로 신뢰성입니다. 공식 문서는 신뢰성을 확보해야 하는데 Confluence는 같은 내용의 콘텐츠를 다루는 문서를 누구나 생성할 수 있기에 독자 입장에서는 그중 어느 것이 공식 문서인 것인지 쉽게 판단할 수 없다고 했습니다.
세 번째로 문서를 쉽게 찾거나 검색하기 어렵다는 점입니다. 앞서 말씀드린 것 같이 공식 문서를 찾기가 어려우며, 누구나 자유롭게 문서를 만드는 Confluence의 특성상 생성되는 URL에 어떤 통일된 규칙이 없기 때문에 URL만으로 해당 페이지가 어떤 내용을 제공하는지 판단하기 어렵다고 말했습니다.
네 번째는 각 팀이나 서비스, 프로덕트에 맞는 아이덴티티를 확보하기가 어렵다고 했습니다. 공식 문서는 디자인만으로도 어떤 주제를 다루는 문서인지 쉽게 파악할 수 있어야 하는데 Confluence는 그 특성상 레이아웃이나 UI 변경에 제약이 있기 때문입니다.
이제 공식 문서는 웹사이트로
위와 같은 이유 때문에 정은 님은 공식 문서는 Confluence가 아닌 다른 방식으로 문서를 작성해 관리하는 것이 더 낫다고 말했는데요. 그럼에도 공식 문서를 계속 Confluence에서 작성해 관리하는 이유로 세 가지가 있을 것 같다고 말했습니다. 첫 번째는 어떤 다른 도구가 있는지 몰라서, 두 번째는 새로운 문서 사이트를 만들거나 기존 문서를 이전할 시간이 없어서, 세 번째는 담아내는 정보의 특성상 사용자 인증 절차 등의 보안 조치가 필요해서 일 것 같다고 짚었습니다. 이어서 여기서 만약 첫 번째와 두 번째 이유 때문에 고민이라면 그 대안으로 웹사이트가 있다고 하며, '아니, 문서 작성할 시간도 없는데 웹사이트를 언제 만들어요?'라고 되물으실 분들을 위해 웹사이트를 만드는 쉽고 간단한 두 가지 방법을 제안했습니다.
첫 번째는 저희 회사에서 자체 개발해 사내 임직원에게 제공하고 있는 LandPress Studio를 이용하는 방법입니다. 정은 님은 뉴스나 블로그 등이 포함된 간단한 프로덕트 포탈이나 이미지와 글을 함께 제공하는 간단한 가이드 문서를 제공하려는 경우에는 LandPress Studio를 이용하면 좋을 것 같다고 전했습니다. LandPress Studio는 미리 정의된 여러 종류의 컴포넌트를 마우스로 끌어다 놓는 방식으로 웹사이트를 만들 수 있는 사내 임직원용 서비스인데요. 외부로 공개된 서비스가 아니기에 여기서 자세히 설명하는 것은 어려울 것 같습니다.
이어서 정은 님은 조금 더 복잡한 구조와 위계를 갖춘 대량의 문서를 제공하고자 할 때에는 SSG를 이용하면 좋다고 제안했습니다. SSG는 텍스트를 기반으로 웹사이트를 만드는 도구이기 때문에 모든 것을 텍스트 기반으로 관리할 수 있다는 점을 장점으로 꼽았는데요. 예를 들어 공식 문서를 여러 페이지로 구성한 Confluence로 작성하면 어떤 특정 용어가 변경돼 이를 공식 문서 전체에 반영할 때 각 페이지를 일일이 열어서 용어를 수정해야 합니다. 하지만 SSG에서는 텍스트 편집기를 열어 전체 문서를 대상으로 찾아 바꾸기를 하면 끝입니다. 대용량 문서 관리에 특화돼 있는 것이죠. 다음으로 디자인 자유도가 높기 때문에 각 문서에 맞는 아이덴티티를 부여하기 좋다고 말했습니다. 또한 SSG를 사용할 때에는 보통 Git 기반으로 로컬에서 마크다운 파일로 문서를 작성할 수 있기 때문에 시스템이 다운되거나 네트워크가 불안정할 때에도 문서를 작성할 수 있으며, 이런 방식으로 작성해서 브랜치 단위로 PR을 이용해 관리하면 웹사이트에는 항상 최신 문서만 존재하기 때문에 독자는 항상 최신 정보만 읽을 수 있다고 말했습니다. 정은 님은 혹시 Git에 익숙하지 않거나 Git 사용을 꺼리는 사용자가 있다면 Git을 CMS 방식으로 관리할 수도 있다고 말하며, 아직 실제 프로젝트에 적용해 보지는 못했지만 Decap CMS라는 도구를 이용하면 Git에 있는 콘텐츠를 마치 Confluence에 있는 것처럼 편집할 수 있다고 공유했습니다.
이후 정은 님은 어려움을 겪고 있다면 저희 팀 Slack 채널로 문의해 달라는 말과 함께 세션을 마쳤는데요. 세션이 끝나자마자 몇몇 임직원분들께서 Slack에 바로 문의를 남겨 주시며 뜨거운 반응을 보여줬습니다.
Slack 메시지를 이해하기 쉽게 작성하는 방법, Hiroki Zenigami 님
LY는 사내 업무용 메신저로 Slack을 사용하고 있습니다. 현재 재택 근무를 기본 업무 형태로 운영하고 있는 만큼 대부분의 업무 관련 커뮤니케이션이 바로 이 Slack에서 진행됩니다. 따라서 Slack에서 최대한 효율적으로 소통하는 것이 굉장히 중요하다고 할 수 있는데요. Hiroki Zenigami 님이 이 상황에 딱 맞는 세션을 준비해 주셨습니다.
먼저 Zenigami 님은 자신을 간단히 소개했습니다. Zenigami 님은 2021년 11월부터 Dev Content 팀에서 테크니컬 라이터로 일하고 있으며, 그 전에는 Ruby on Rails 기반의 웹 엔지니어였습니다. 현재 LINE Developers 사이트에서 주로 LINE API 개발자용 문서를 작성하고 있고, 이후 세션에서 소개할 사내 용어집 Words의 일본어 버전 운영 및 관리를 맡고 있습니다. 사외 활동으로는 現場で使える Ruby on Rails 5速習実践ガイド라는 책 집필에 참여하고, Software Design (Software Design) 2013 February라는 책에 기사를 싣기도 했습니다.
Zenigami 님은 본격적으로 시작하기 전에, 이번 세션에서 제안하는 것은 한 가지 예시이며 꼭 이를 따를 필요는 없다고 전제했습니다. 소통하는 각 인원이 만족하는 다 른 방식이 있다면 그 방식을 유지하는 게 가장 좋은 방법이라고 말했습니다. 또한 이번 세션에서는 이모지나 리액션, 스레드 등 Slack에서 제공하는 여러 기능이나 굵은 글씨나 인용문, 목록 등을 이용하는 방법은 다루지 않고, 순수하게 글쓰기 그 자체만 다룰 것이라고 전제했습니다.
이제 본론으로 들어가서, Zenigami 님이 전달하는 내용의 핵심은 메시지를 보낼 때 수신자가 추가로 일정을 확인하거나 이전 메시지 혹은 메일을 찾아볼 필요 없이 5W1H를 최대한 명확하게 담는 것이었습니다. Zenigami 님이 제시한 아래 예시를 보시면 이해가 쉬울 것 같습니다.
지양해야 할 메시지 | 지향해야 할 메시지 |
---|---|
@channel Are you ready for today's meeting? | @group-dev-content The Dev Content Weekly meeting is today at 15:00. To make this a meaningful meeting, please take a quick look at the agenda. If you have items for discussion, please update the wiki before the weekly meeting starts. Wiki: https://example.com Zoom: https://example.com |
Zenigami 님은 위 두 메시지를 5W1H 관점에서 아래와 같이 비교 분석했습니다.
5W1H | 지양해야 할 메시지 | 지향해야 할 메시지 |
---|---|---|
Who | @Channel | @group-dev-content |
When | Today | Today at 15:00 |
Where | - |
|
Why | - | To make this a meaningful meeting |
What | Meeting | The Dev Content Weekly meeting |
How | Ready |
|
위와 같이 받는 사람을 배려한 메시지를 보낸다면 하루에도 수백, 수천 개의 메시지가 오가는 Slack 채널에서 불필요한 알람이 울려 해당하지 않는 사람까지 메시지를 확인하게 만드는 일도 줄어들고, 정보가 부족해 다시 되묻기 위한 메시지도 줄일 수 있을 것 같은데요. 그렇다면 꼭 필요한 사람에게 꼭 필요한 정보를 한 번에 전달하는 위와 같은 메시지를 작성하는 훈련은 어떻게 해야 할까요?
Zenigami 님이 제안하는 방법은 글을 잘 쓰기 위한 방법과 크게 다르지 않습니다. 메시지를 보내기 전에 아무 메모 앱이나 실행해서 거기서 메시지를 먼저 써보고 메시지 수신자의 관점에서 한 번 읽어보는 것입니다. 머리에 생각나는대로 바로 메시지를 적어서 전송하는 것이 아니라 이렇게 한 번 옮겨 적는 과정을 거치는 것만으로도 생각보다 많은 부분을 보완할 수 있을 것입니다.
문서 구조를 이해하는 한 가지 관점, 박하늬 님
하늬 님은 개발자로 일하다 재작년에 테크니컬 라이터로 LY에 합류했다고 자신을 소개했습니다. 하늬 님은 자신이 개발자로 일할 때에도 기술 문서를 작성할 일이 종종 있었는데 당시에는 구성이나 목차를 잡는 것이 상당히 어렵게 느껴졌다며, 이번 세션에서는 자신이 개발자였을 때 알았으면 좋았을 것 같다고 생각한 내용으로 준비했다고 말했습니다.
기술 문서 콘텐츠의 세 가지 유형
하늬 님은 소프트웨어 기술 문서를 작성할 때 문서에 담기는 콘텐츠의 특성을 고려해 문서를 구성하면 독자가 훨씬 더 쉽게 이해할 수 있는 문서를 만들 수 있다고 말했습니다.
소프트웨어 기술 문서에는 설치 가이드, 백서, FAQ, 개요 문서, API 레퍼런스, 튜토리얼 등 다양한 종류가 있는데요. 각 문서가 제공하는 정보의 성격에 따라 아래와 같이 세 가지로 콘텐츠를 분류할 수 있다고 말했습니다.
- 개념(concept): 이해지향적(understanding-oriented) 콘텐츠로 독자의 이해가 목표입니다. 서비스나 프로덕트의 철학이나 개념, 구조 등 줄글로 읽을 수 있는 콘텐츠로 정형화된 틀이 없기 때문에 가장 작성하기 어려운 콘텐츠입니다. 세부 사항을 전부 나열하기보다는 간결하고 명료하게 전달하는 것에 초점을 둬야 합니다.
- 절차(task): 목표지향적(goal-oriented) 콘텐츠로 특정 목적을 달성하는 방법을 알려주는 게 목표입니다. 설치 가이드, 튜토리얼 등을 생각하시면 됩니다. 각 단계를 독자가 취할 액션 중심으로 명확하게 설명하는 게 중요합니다.
- 참조(reference): 정보지향적(information-oriented) 콘텐츠로 특정 정보가 필요할 때 찾아보는 콘텐츠입니다. 독자가 사전처럼 필요한 부분만 찾아서 읽기 때문에 원하는 정보를 찾아가기 쉽도록 작성해야 하며, 또한 콘텐츠 각 부분의 형식을 통일해 어느 부분을 찾아봐도 독자가 같은 형식으로 정보를 취득할 수 있도록 작성해야 합니다. 이 유형의 콘텐츠는 대부분 작성하는 틀이 정해져 있기 때문에 가장 작성하기 수월한 콘텐츠입니다.
기술 문서 콘텐츠를 분류하는 이유
하늬 님은 이와 같이 콘텐츠 유형을 머리에 넣어 두고 문서를 작성하기 시작하면 문서를 처음 작성할 때의 막연함을 많이 줄일 수 있으며, 추후 문서에 내용을 추가할 때에도 정보의 성격에 따라 어느 위치에 추가해야 할지 바로 파악할 수 있다고 말했습니다. 또한 독자 입장에서도 장점이 있다고 말했는데요. 콘텐츠 유형을 잘 분류해 배치해 놓으면 독자 입장에서는 어떤 문서가 어느 위치에 있을지 쉽게 예측할 수 있기 때문입니다.
문서의 종류를 이용해 문서 사이트 구조 설계하기
하늬 님은 다음으로 이 같은 콘텐츠 유형 분류를 문서 구조에 적용할 때 알아두면 좋을 두 가지 팁을 제시했습니다.
첫 번째는 '같은 콘텐츠 유형을 최대한 함께 모아 놓는다'입니다. 개념 유형 콘텐츠는 개념 유형끼리, 절차 유형 콘텐츠는 절차 유형끼리, 참조 유형의 콘텐츠 참조 유형끼리 모아 놓는 것입니다. 하늬 님이 준비해 주신 아래 GitHub Docs의 Webhooks 문서 예시를 보면 같은 유형끼리 모은다는 것이 어떤 의미인지 쉽게 이해할 수 있을 것 같습니다. 왼쪽 사이드바를 보면 목차가 다섯 개 나열돼 있습니다. 첫 번째는 웹훅이 무엇인지 소개하는 문서이고, 두 번째는 웹훅의 종류를 설명하는 문서로 각각 한 페이지짜리 문서입니다. 세 번째는 웹훅 기능에서 제공하는 모든 이벤트와 페이로드를 한 페이지에 길게 나열한 문서입니다. 네 번째와 다섯 번째는 웹훅 사용법을 크게 두 가지 주제로 나눠 놓은 문서로 각 문서에 여러 하위 페이지가 존재합니다.
이 문서를 앞서 소개한 세 가지 유형으로 분류해 보면 다음과 같습니다. 이와 같이 같은 유형끼리 모아 놓으면 독자가 필요한 정보에 보다 쉽게 접근해 얻어갈 수 있습니다.
하지만 현실에서는 이와 같이 명확히 나누는 게 어려운 경우가 많습니다. 가지고 있는 정보를 셋 중 하나의 유형에 꼭 들어맞는 콘텐츠로 작성하는 것도, 기존에 작성한 콘텐츠가 셋 중 어떤 유형인지 분별하는 것도 쉽지 않습니다. 각 유형에 따라 문서의 양이 달라서 유형에 따라서만 묶고 나누는 게 어려운 경우도 있고요.
여기서 하늬 님은 두 번째 팁을 제시합니다. '최대한 첫 번째 팁을 지키되, 거기에 너무 얽매이지 말라'입니다. 경우에 따라서 독자의 니즈를 더 잘 충족시킬 수 있는 방향이 있다면 꼭 콘텐츠 유형에 따라 분류하지 않아도 괜찮다며, 예를 들어 문서를 읽는 독자가 일반 사용자와 개발자로 나뉜다고 할 때 콘텐츠 유형보다는 각 독자에 따라서 문서를 나누는 게 더 좋을 수도 있다고 말했습니다. 또한 때에 따라서는 문서의 양이 많지 않은데 독자가 하나의 목적을 달성하기 위해 여러 문서를 넘나들게 하는 것보다는 한 군데로 모으는 것이 좋다고 말했습니다.
글쓰기의 안티 패턴, Ryotaro Furuki 님
LINE Developers 사이트 문서를 담당하고 있는 Furuki 님은 이번 세션에서 '하지 말아야 할 것들을 파악해 보다 좋은 문서를 만드는 법을 알려주셨습니다.
Furuki 님이 소개한 첫 번째 안티 패턴은 문서를 읽을 독자를 정의하지 않고 쓰기 시작하는 것입니다. 사내 대상인지 사외로 배포할 문서인지, 초심자인지 전문가인지, 신입인지 경력인지 등 독자를 가정하지 않고 문서를 작성하면 필수 정보가 포함되지 않거나 필요 없는 정보가 포함되는 일이 발 생할 수 있고, 용어와 약어가 별다른 설명 없이 사용돼 독자가 문서를 이해하기 어렵게 만들 수 있습니다.
두 번째 안티 패턴은 제대로 이해하지 못한 상태에서 문서를 작성하는 것입니다. 가장 좋은 방법은 내용을 완전히 이해한 뒤 문서를 작성하는 것이겠지만, 바쁜 업무 중에는 상황이 허락하지 않는 경우가 많을 것입니다. 그럴 때는 관련 내용을 잘 아는 전문가한테 리뷰를 받는 과정이 필요합니다. Furuki 님은 리뷰를 주고받는 과정에서의 팁을 공유했는데요. 먼저 리뷰를 요청할 때에는 상대방이 이 문서의 어떤 포인트를 중점적으로 확인해 주길 바라는지 전달하는 것이 좋습니다. 예를 들어 사용 가이드의 경우 절차대로 진행했을 때 문제없이 실행이 되는지에 중점을 두고 봐달라고 요청할 수 있습니다. 또한 리뷰하는 입장에서는 코멘트의 수준을 나눠서 피드백을 주면 좋습니다. 꼭 수정해야 하는 것, 수정하면 좋은 것, 꼭 수정하지 않아도 되는 것 등으로 나눠서 전달하면 리뷰를 요청한 사람이 우선순위를 정해 자신의 자원을 효율적으로 사용할 수 있습니다.
세 번째 안티 패턴은 개요 없이 바로 문서를 작성하기 시작하는 것입니다. 좋은 문서를 작성할 때 먼저 개요를 작성하면 정보를 잘 정리하고 체계화할 수 있습니다. Furuki 님은 개요를 잘 작성할 수 있는 세 가지 팁을 소개했는데요. 첫 번째는 '전체적인 설명을 먼저 작성한다'이고, 두 번째 팁은 '개요를 먼저 제공한 뒤 세부 정보를 제공한다'이며, 세 번째는 '위계와 같은 구조를 의식하고 개요를 작성한다'입니다.
이와 관련해 Furuki 님이 제시한 다음 예시를 보면 이해하기 쉬울 것 같습니다. 아래 문서를 보면 목적지와 소요 시간 등 중요한 내용이 문서의 뒤에 배치돼 있어서 독자가 문서를 다 읽고 나서야 알 수 있습니다.
반면 아래 문서는 목적지와 소요 시간을 먼저 파악한 뒤 세부 사항을 만나게 됩니다. 이와 같이 작성하고자 하는 문서의 구조를 의식하며 전체적인 설명과 개요를 먼저 제공한 뒤 세부 정보를 제공하는 방식으로 문서를 작성하면 독자에게 보다 친절한 문서를 만들 수 있습니다.
네 번째 안티 패턴은 초안에 너무 매달리며 끝내지 못하는 것입니다. Furuki 님은 초안을 너무 완벽히 완성하려고 하지 말라고 조언했습니다. 아직 문장이 엉성하거나 완벽히 완성된 느낌이 들지 않더라도, 우선 초안을 빠르게 마무리한 뒤 다른 사람에게 리뷰를 요청해 피드백을 받아 문서를 완성시켜 나가는 것이 훨씬 나은 방법이라고 말했습니다.
다섯 번째 안티 패턴은 작성한 문서를 다시 보지 않는 것입니다. Furuki 님은 작성한 뒤 자신도, 동료도, 리드도 리뷰하지 않은 문서를 만들면 안 된다고 말하며, 간단하게라도 리뷰 프로세스를 갖추고 모든 문서를 해당 프로세스대로 리뷰해야 한다고 말했습니다. Furuki 님은 다른 사람에게 리뷰를 요청하기 어려워 스스로 리뷰해야 하는 상황에서 유용하게 사용할 수 있는 팁도 공유했는데요. 스스로 리뷰할 때는 작성한 뒤 조금 시간이 지난 뒤 다시 읽어보면 좋습니다. 시 간이 흐르면 작성하던 시점이 아닌 조금 다른 시점으로 마치 독자가 된 것처럼 읽어볼 수 있기 때문입니다. 다음으로 작성한 문서를 도구를 이용해 기계 음성으로 들어보면 좋다고 말했습니다. 이렇게 음성으로 들으면 눈으로 볼 때에는 발견하지 못한 어색한 부분이나 오탈자 등을 찾아낼 수 있다고 했습니다. 마지막으로 점검해야 할 포인트를 선정해 해당 포인트 단위로 읽어보는 것을 권했습니다. 예를 들어 이번에 읽을 때에는 문서에 포함된 URL을 전체적으로 확인한다든지 혹은 문서에 포함된 이미지를 전부 확인한다든지와 같이 중점적으로 점검할 체크 포인트를 선정하고 이 체크 포인트 위주로 확인하며 읽으면 실수를 예방할 수 있다고 말했습니다.
마지막 안티 패턴은 작성한 문서를 방치하는 것입니다. 대부분의 문서는 그 안에 담긴 정보가 꾸준히 갱신되기 때문에 문서를 함께 업데이트해 주지 않으면 문서가 잘못된 정보를 전달할 수 있다고 말했습니다. 서비스나 프로덕트의 성장에 맞춰 문서도 문서도 주기적으로 업데이트해야 하며, 서비스나 프로덕트가 종료되거나 더 이상 문서를 관리하지 않게 됐다면 그 사실 또한 사용자에게 제대로 알려야 한다고 말했습니다.
Words 100% 활용하기, 최소영/김지현 님
세상의 모든 집단에서는 공식적으로든 비공식적으로든 의사소통의 효율을 높이기 위해 자체적으로 여러 가지 줄임말이나 용어를 만들어 활용하기 마련입니다. 그렇게 생겨난 용어는 분명 기존 조직원간의 소통 효율은 높여주지만, 새로 조직에 합류한 사람들에게는 넘어야 할 장애물로 작용하곤 합니다. 이에 저희 팀에서는 사내 임직원을 위한 용어 사전인 Words를 개발해 운영하고 있습니다. Words는 새로 합류한 조직원뿐만 아니라 다른 팀과 협업하는 많은 임직원의 호응을 얻고 있는데요. 최소영 님과 김지현 님께서 이 Words를 보다 잘 활용할 수 있는 방법을 소개했습니다. 중간중간 사내 용어 맞추는 게임과 함께 진행돼 편안한 마음으로 들을 수 있는 세션이었습니다.
이 글을 읽고 계신 분들 중에서도 업무 중 처음 보는 용어나 줄임말에 당황하신 적이 한 번은 있으실 것 같습니다. LY에서는 이와 같이 낯선 약어와 어려운 전문 용어에 허덕이는 임직원을 위해 Words를 제공하고 있는데요. 비슷한 어려움을 겪고 계시다면 Words와 같은 서비스를 제공하는 것을 한 번 생각해 보셔도 좋을 것 같습니다. Words와 관련한 더욱 자세한 사항은 테크니컬 라이터 강정일 님이 작성한 사내 용어 사전, LINE Words 오픈 여정기를 참고하시면 좋을 것 같습니다.
의미 전달이 잘 되는 번역 팁 소개, Kozue Takasaki 님
Takasaki 님은 IT 출판 회사의 편집자겸 기자로 사회 생활을 시작해 외국계 기업의 IT 헬프 데스크와 고객 지원 부서를 거쳐 2018년에 이 회사에 입사했습니다. 현재 Dev Content 팀에서 LINE Developers 사이트의 문서를 담당하고 있습니다.
Takasaki 님은 이 세션은 영어가 모국어가 아닌 분들만 대상으로 삼는다고 범위를 한정하며 세션을 시작했습니다. 현재 LY에서는 여러 나라의 사람이 여러 언어 를 사용하며 함께 근무하고 있습니다. 따라서 Slack이나 이메일을 작성할 때 영어를 병기해 달라는 요청이 늘고 있는데요. 많은 사람들이 영어 사용에 익숙하지 않아서 어려워하고 있습니다.
Pro-drop 언어와 Non-pro-drop 언어
Takasaki 님은 먼저 언어의 특성을 살펴보며 많은 분들이 어려워하는 원인을 찾았습니다. 언어는 아래와 같이 Pro-drop 언어와 Non-pro-drop 언어로 나눌 수 있는데요. 경우에 따라서 특정 대명사를 생략할 수 있는 Pro-drop 언어는 그렇지 않은 Non-pro-drop 언어로 번역하기가 어렵다고 말했습니다.
아래는 Takasaki 님이 준비한 일본어 예시입니다. 한국어에도 같은 특성이 있기 때문에 Pro-drop 언어와 Non-pro-drop 언어의 차이를 쉽게 이해하실 수 있을 것 같습니다. Pro-drop 언어 사용자는 자연스럽게 문장의 주어나 대명사를 생략해서 문장을 작성하곤 하는데 이와 같은 문장을 기계 번역이나 Slack 번역봇 등을 이용해 번역하면, 해당 도구가 비어 있는 문장의 구성 요소를 임의로 채워 넣으면서 문장의 의미가 달라질 수도 있다고 말했습니다.
각 언어 사용자는 관습이나 문맥을 통해 생략된 구성 요소가 무엇인지 쉽게 유추할 수 있지만 기계 번역기는 아직 그런 능력이 부족합니다. 따라서 주어나 대명사를 생략한 일본어를 그대로 기계 번역에 넣고 한국어로 번역하면 의미가 와전되거나 파악하기 어려운 결과가 나올 수 있는 것이죠.
따라서 도구를 사용해 번역할 때 이 점을 잘 고려해 원문을 사용하면 의미가 잘 전달되게 번역되도록 만들 수 있다고 말하며, 이와 같은 도구의 사용법과 번역하기 쉬운 원문을 작성하는 요령을 공유했습니다.
추천하는 번역 도구와 사용 팁
가장 먼저 소개된 도구는 DeepL Pro입니다. DeepL Pro는 사내에서 사용하려면 관련 부서의 보안 검토를 거쳐 회사에서 계약한 계정으로 사용해야 하지만, 특히 일본어에 한해서는 소스 문장에서 생략된 주제를 보완해 주기도 하고, 소스와 결과에서 사용할 용어를 미리 사전으로 등록해 번역 결과의 품질을 향상시킬 수도 있습니다. 또한 번역 결과를 다시 원문으로 번역해 볼 수 있는 기능도 아주 유용하다고 소개했는데요. 번역 결과를 다시 소스 언어로 번역해 보면서 잘못 번역된 부분이나 어색한 부분을 확인해 원문을 수정하면서 번역 품질을 향상시킬 수 있다고 말했습니다.
또한 Takasaki 님은 둘 이상의 번역 도구를 사용해 각 결과를 비교해 보면 좋다고 말했습니다. 번역 서비스마다 결과가 조금씩 다른 경우가 많기 때문에 DeepL Pro뿐 아니라 Google 번역이나 Yarakuzen 등 다른 여러 번역 서비스에서 산출된 결과를 비교하면 더 나은 번역 결과를 얻을 수 있다고 말했습니다.
아래 예시를 살펴보면 '소프트웨어 개발을 종료했습니다'라는 문장을 번역했을 때, A 도구의 결과에는 '이제 개발을 하지 않겠다'는 의미가 분명히 들어가 있는 용어(terminated)로 번역됐습니다. 반면, B에서는 '개발이 완료됐다(completed)'로 번역됐는데요. 이 문장은 '이번 개발은 완료됐고 다음 버전 개발이 진행될 수도 있다'와 같이 해석이 될 수도 있어서 앞 문장과는 다른 의미가 될 수 있습니다.
따라서 자신이 원래 의도한 것에 맞게 적절히 영어 단어를 선택해야 한다고 말하며, 이때 도움을 받을 수 있는 도구 중 하나로 Reverso를 소개했습니다. Reverso는 Context라는 기능을 제공하는데요. Context에서 단어나 표현을 검색하면 소스 언어에서 해당 단어나 표현이 타깃 언어에서 어떤 단어나 표현으로 번역됐는지 다양한 문맥의 결과를 확인할 수 있습니다.
다음으로 Collins를 소개했습니다. Collins 역시 문맥 검색이 가능하며, 예문으로 신문 등 미디어 자료가 많이 나오기 때문에 보다 정확한 표현을 접할 수 있다고 말했습니다. 또한 단순히 단어 뜻만 제공하는 게 아니라 유의어와 단어가 사용된 문장, 활용형 등을 함께 확인할 수 있어서 번역 결과 확인 및 품질 향상에 많은 도움을 받을 수 있다고 말했습니다.
이렇게 어느 정도 문장이 완성되면 번역 도구를 이용해 음성으로 한 번 들어보는 것을 권했습니다. 그중 Papago는 한국어 번역 성능이 좋고, 발음 듣기 기능의 일본어 억양이 좋다며 추천했습니다.
다음으로 이와 같이 여러 가지 번역 도구를 이용할 때 사용하기 편한 웹브라우저로 Microsoft Edge를 소개했습니다. 세로 탭을 제공하기 때문에 번역 과정에서 여러 번역 도구를 번갈아 사용해야 할 때 편리하다고 말했습니다.
마지막으로 소개한 도구는 ChatGPT입니다. 이미 많은 분들이 사용하고 계실 것 같은데요. ChatGPT를 이용해 번역할 때 바로 번역 문구를 던지지 말고, 미리 ChatGPT에게 어떤 단어는 어떤 단어로 번역해 달라고 요청하면 번역 결과 품질을 높일 수 있다고 했습니다. 또한 마치 동료에게 리뷰를 받는 것처럼 ChatGPT에게 번역 결과를 리뷰해 달라고 요청하는 것도 좋은 방법이라고 말했는데요. 오탈자 및 문법 오류는 물론 잘못된 부분(예를 들어 과거의 사실을 말하면서 연도를 '3023'으로 잘못 기입한 경우 '2023'으로 교정)을 짚어주기도 한다고 말했습니다.
이와 같이 다양한 도구를 사용하면 글로벌 회사에서 익숙지 않은 언어로 소통할 때 많은 도움을 받을 수 있다고 말하며 세션은 마무리됐습니다.
DocOps 인사이트 - 기술 문서 관리 경험 공유, 강정일 님
DevOps라는 말은 많이 들어보셨을 텐데요. 최근 문서 작성 및 관리 방법과 관련해 DocOps라는 개념이 등장했습니다. 이번 세션에서는 강정일 님이 자신이 맡았던 기술 문서 프로젝트 중 이 DocOps 개념을 응용해 적용했던 경험을 소개했습니다.