LINE Corporation이 2023년 10월 1일부로 LY Corporation이 되었습니다. LY Corporation의 새로운 기술 블로그를 소개합니다. LY Corporation Tech Blog

Blog


그것이 알고 싶다 - 왜 개발자는 글을 못 쓸까?

개발자는 글을 못 쓰는 것일까? 

아니, 개발자는 글을 안 쓰는 것일까? 

아니, 개발자는 글을 쓰기 싫은 것일까? 

물론 글을 잘 쓰는 개발자도 계시고 책을 집필한 개발자도, 잡지에 글을 기고하는 개발자도 계십니다. 저는 지금 모든 개발자가 글을 못 쓴다고 말하려는 것은 아닙니다. 어쩌면, 막상 쓰면 잘 쓸 수 있는데 글을 쓰겠다고 마음을 먹고 열 손가락을 키보드 자판 위에 살포시 올려놓기까지가 오래 걸리는 것일 수도 있습니다.

저는 현직 테크니컬 라이터이자 전직 개발자로서 현장에서 겪은 경험을 바탕으로 이 현상을 심층 분석해 보려고 합니다. 단, 분석만입니다. 마치 매년 12월~1월에 서점에서 만나볼 수 있는 다양한 자기 계발서 마냥 상당히 이론적인 내용을 나눕니다. 누군가에겐 매우 따분한 이야기가 될 수 있겠지요. 누구나 머리로는 알고 있는 내용이지만 실천으로 이어질 가능성이 현저히 낮은 내용 말입니다.

하지만 여러분, 이 글이 여러분을 만나게 된 지금이 어떤 시기입니까? 크리스마스와 연말을 앞둔 시점입니다. 사무실마다 싱숭생숭한 마음들이 둥실둥실 떠다니고, 업무에 집중은 안 되고, 시선은 창밖을 정처 없이 떠돌고, 들썩대는 엉덩이를 겨우 붙여 놓고 간신히 앉아 있는 지금입니다! 정녕 일이 눈에 들어오십니까? 그럴 리가요. 때마침 LINE Engineering 블로그를 화면에 띄워 놓고 열심히 일하는 모습을 연출할 수 있는 기회가 여러분에게 주어진 것입니다. 이왕 이렇게 된 것, 편한 마음으로 한 번 읽어 보시겠어요?

분석 착수

이유를 도출해 보기 위해 마인드 맵을 생성합니다. 메인 토픽에 '개발자 입장'이라고 적고 개발자로 빙의합니다. 떠올려 보니 금년 상반기에 Node.js 모듈을 개발할 기회가 있었습니다. 위키에서 메타 데이터를 뽑아 유의미한 데이터로 가공하는 모듈을 만들었습니다. 그런데 모듈 사용 가이드를 작성하려고 하니 아니 웬걸! 문서를 쓰기가 정말 싫었습니다. 게다가 저는 사내 교육을 통해 주석을 잘 작성하자는 메시지를 전하고 있는 사람으로서 솔선수범하고자 JSDoc 문법에 기반하여 모듈 코드에 주석을 쓰려고 했는데요. 아니 웬걸! 주석을 쓰기가 정말 싫었습니다. 역시 사람은 상대방의 입장이 되어봐야 상대방을 온전히 이해할 수 있나 봅니다. 그런데 말입니다. 생각해 보니 저도 개발자였습니다.

다른 사람은 관심 없을 내 얘기

개발자였을 때 나는 문서를 잘(well and often) 썼는가? 떠올려 보니 어쩔 수 없는 상황에서 '기술 문서'라는 산출물을 작성한 적이 한 번 있었습니다. 당시 다니던 회사의 특정 모델 라인에 신규 파트너사의 과금 모듈을 사상 처음으로 탑재해야 했습니다. 맨땅에 헤딩을 해 가며 성공적으로 해당 모듈을 탑재했습니다. 생각해 보면 파트너사가 제공한 문서가 매우 훌륭했던 덕에 수월하게 탑재했던 듯합니다. 모듈을 직접 탑재한 저는 해당 모듈을 어떻게 활용하면 되는지 알았지만 모듈과 연동 작업에 착수해야 하는 여러 컴포넌트 담당자들은 그렇지 않았습니다. 그래서 개발 가이드를 만들어 달라는 요청을 받았습니다. 기억을 더듬어 보니 당시 문서를 PPT로 작성했습니다. 아, 흑역사입니다! 문체도 '~하삼', '~하지마삼'으로 작성했던 것이 떠오릅니다. 괜히 떠올려서 오늘 밤 이불킥을 예약합니다.

당시 다니던 회사에는 테크니컬 라이팅 팀이란 게 없었습니다. 그래서 물어볼 사람이 없었고 그런 분야가 존재하는지조차도 몰랐습니다. 이후 테크니컬 라이팅 팀이 구성되며 기술 문서 사내 교육이 생겨났고, 전 결코 원치 않았지만 팀에서 차출돼 참석했습니다. 그런데 제가 너무 문외한이었나 봅니다. 당시 교육에서 무슨 말씀을 하시는지, 내가 무슨 내용을 배우고 있는지 정확하게 인지하지 못했던 것 같습니다. 그리고 마음에 저항이 있었습니다. '개발하기도 바쁜데 무슨 문서를 쓰라는 거지?' 그래서인지 지금 저는 개발자 여러분의 심정을 누구보다 잘 이해... 해야 하는데 잘 못하고 있네요! 반성합니다.

다시 본론으로

다시 본론으로 돌아와서 제가 이번에 개발하는 과정 중, 그리고 개발 후에 문서를 쓰려고 했을 때 느꼈던 이질감 혹은 불편함은 무엇이었나 자문합니다. 신기하게도 생각이 쏙쏙 고개를 내밀어 다음과 같이 세 항목을 도출했습니다.

어디서 많이 본 듯한 구조입니다. 그렇습니다! 제가 운동하기 싫은 이유와 어찌 이리 같은지요!

귀찮다, 어렵다, 바쁘다

어쩌면 세계 만민이 공감할 수 있는 이유인 것 같기도 합니다. 운동을 좋아하는 사람에겐 이런 이유가 존재조차 하지 않겠지만 운동이 싫거나 운동과 친하지 않은 사람의 입장은 다릅니다. 운동이 귀찮고 운동이 어렵고 운동하기엔 인생이 너무 바쁩니다. 그런데 말입니다. 귀찮고 어렵고 바빠서 사랑받기를 거부하시는 분 계실까요? 귀찮고 어렵고 바빠서 급여 계좌 개설을 거부하시는 분 계실까요? 그렇습니다. 들여다보면 마음의 문제입니다. 잘 못해도 어떻게든 하고 싶은 마음이 있으면 하게 됩니다. 하기 싫은 일도 해야만 하는 이유가 있으면 몸이 움직입니다.

귀찮고 어렵고 바쁘기 때문에 잘 못하고 하기 싫은 것이기도 하면서, 동시에 잘 못하고 하기 싫기 때문에 글 쓰는 것이 귀찮고 어렵고 성가시게 느껴지는 것일 수 있습니다. 무한 악순환입니다. 그래서! 이 고리를 어딘가에선 끊어야 하기 때문에 왜 귀찮은지, 왜 어려운지, 왜 싫은지 자세히 살펴보도록 하겠습니다.

귀찮다

귀찮기 때문에 글을 못 쓰고, 귀찮기 때문에 글을 안 쓰고, 귀찮기 때문에 글쓰기가 싫습니다. 귀찮아서 아예 쓸 시도를 하지 않거나 쓰긴 쓰는데 귀찮으니까 많은 내용을 생략해 버립니다. 귀찮으니까 누구를 위해 쓰는지는 물론 무엇을 쓰는지도 고려하지 않습니다. 그래서 문서 목차를 도출하기도 전에 키보드에 손가락을 얹습니다. 그리고 손가락을 바삐 움직입니다. 그 결과 문서에 반드시 필요한 내용이 누락됩니다. 주어나 타동사에 대한 목적어, 조사 혹은 핵심 단어를 빠뜨리고 키보드를 두들깁니다.

글 쓰는 것이 귀찮다고 여겨지는 이유를 다음과 같이 묵상해 보았습니다.

저자가 묵상해 본 글쓰기가 귀찮은 이유

코딩은 우리가 흔히 읽고 쓰는 언어와는 다른 형태로 뜻을 전달하고 구사하는 행위입니다. 그래서 애초에 프로그래밍 ‘언어’라는 표현을 사용하는 것일지도 모르겠습니다. 프로그래밍 언어는 매우 짧은 단어들로 논리를 구현하도록 돕습니다. 우리가 일상에서 구사하는 긴 문장으로 코드를 작성해서 CPU에 전달하는 것보다는 짤막한 단어들로 하는 것이 CPU 입장에선 보다 빠르게 처리할 수 있겠지요? 단거리 주자가 하루아침에 장거리 주자가 되기는 어려운 것처럼 축약하는 것이 익숙한 개발자 입장에선 자신의 생각을 평소에 자주 사용하지 않는 문어체로, 코드보다 훨씬 긴 단어들의 조합으로 표현해 내는 것은 어려울 수 있습니다. 그래서 귀찮게 여겨질 수 있습니다.

Rules
  • Branch name === Pull Request name
  • 2 approve

얼마 전 문서를 검토하다 만난 문서의 한 부분. 애석하게도 이것은 ‘글’이 아닙니다…

테크니컬 라이터 처방 - 귀찮은 그대에게

결국 애정을 키우거나 익숙해지거나. 이 두 방법 중 하나를 선택해서 접근해야 할 듯합니다. 사람 사이의 정(情)도 볼수록 만날수록 쌓이고 커지듯이 무엇이든지 누구든지 더 볼수록 만날수록 익숙해집니다. 익숙해지면 잘하게 되는 발판이 마련되기도 합니다. 잘하면 그 일이 좋아집니다. 선순환입니다.

귀찮게 느껴지는 일이 좋아지려면 작은 성취를 얻어야 합니다. 오늘 스쿼트 5번 하고 내일 6번 해내면 세상 뿌듯합니다. 오늘 퇴근하기 전에 여러분이 구현한 코드가 하는 일을 한 문장으로 설명해서 써 보세요. 그리고 내일은 한 문장 더 써 보세요. 이런 식으로 조금씩 기록을 남겨가면 스스로도 대견하고 익숙해집니다. 세상 이치가 다 그런 것 같습니다. 뭐든 익숙해지려면, 그리고 잘하려면 꾸준히 해야 하는 것 같습니다.

개발자로서 작성해야 하는 글은 문학적 소양이 나타나야 하는 글이 아니기 때문에 '글빨'의 우선순위가 높지 않습니다. 일단 독자에게 제공해야 하는 내용이 잘 들어갔는지, 독자 수준(예: 초보자, 숙련자)은 고려됐는지, 내용이 논리적으로 잘 구분이 됐는지와 같은 측면에서 고민해 보기를 권장합니다. 작문에서 흥미를 느끼지 못했어도 정보 설계를 하다가 새로운 흥미를 느끼게 될 수도 있습니다!

어렵다

‘확찐자’ 탈출을 위해 전 운동을 해야만 하는 상황입니다. 나날이 체중 기록을 경신하고 있습니다. 이번엔 어떤 운동을 도전해 볼지 고민입니다. 어깨 깡패가 되고 싶은데 그러려면 웨이트 운동을 해야 할 것 같아서 헬스장에 등록할까 고심하고 있습니다. 전 헬스장이 어렵게 느껴집니다. 헬스장마다 조금씩 다른 종류의 기구가 있어서 종종 처음 보는 기구와 마주치기 때문입니다. 어떻게 사용하는지 모르기 때문에 어렵게 느껴지고, 또 어떻게 사용하고 어떤 자세로 하는 게 맞는지 누군가에게 물어보는 것이 어려워 등록을 꺼리게 됩니다.

이와 같이 문서를 어떻게 시작할지 몰라서, 시작이 두려워서, 혹은 누구에게 물어볼지 몰라서 글 쓰는 것이 어렵게 느껴질 수 있습니다. 혹은 내용의 범위나 독자 범위를 선정하는 데에 어려움을 느낄 수 있습니다. 글은 상세하게 쓰라는 말씀도 들어보셨을 테고 간결하게 쓰라는 말씀도 들어보셨을 것입니다. 얼마나 자세히 써야 하는지 혹은 어떻게 간결하게 만드는지 모를 수 있습니다. 외부 배포용 문서는 내부용과 톤이 어떻게 달라야 하는지 전혀 감이 잡히지 않을 수 있습니다.

저자가 묵상해 본 글쓰기가 어려운 이유

테크니컬 라이터 처방 - 어려움을 겪고 있는 그대에게

해 보지 않아서 어려운 것이지 한 번 해 보면 그리 어렵지 않습니다. 꼬리를 무는 질문의 답을 찾기 어려울 때는 전문가의 도움을 받는 것이 제일 빠른 길이 아닐까 합니다. 헬스장에서 트레이너에게 도움을 받듯이, 운전면허를 따기 위해 운전 연수를 받듯이 말입니다. 여러분 회사에 테크니컬 라이터가 존재한다면 테크니컬 라이터를 찾아가 보시기 바랍니다. 쌍수 들고 환영하며 기쁜 마음으로 여러분의 가려운 곳을 벅벅 긁어 드릴 겁니다. LINE에서는 글쓰기 실력을 향상시키고자 하는 LINER들을 위해 격월로 P.O.W.E.R 라이팅이라는 글쓰기 교육 과정을 제공하고 있으며 다양한 직군의 사람들이 교육에 참석해 글쓰기를 가로막는 장벽을 부수고 있습니다.

LINE처럼 사내에 혹은 지인 중에 테크니컬 라이터가 있다면 더할 나위 없이 좋겠지만 혹 테크니컬 라이터가 없어 어떻게 할지 모를 때는 다른 사람들이 쓴 문서를 여럿 읽어 보시기 바랍니다. 읽다 보면 패턴이 보입니다. 읽다 보면 내 글의 개선점이 보입니다. 그럼 무엇을 읽어야 하느냐? 잘 쓴 사람이 쓴 글 혹은 많이 읽히는 글을 읽어 보면 좋겠지요. 개발자 가이드를 잘 쓰고 싶다면 LINE 개발자 사이트나 Android 개발자 사이트, Apple 개발자 사이트 등 여러 개발자 사이트에 올라온 개발 가이드를 읽어 보세요. API 문서를 잘 쓰고 싶다면 Stripe API 문서를 읽어 보세요(여러 테크니컬 라이터들이 추천하는 사이트입니다). 이때 주의할 점이 있습니다. 문서를 읽으며 '뭔가를 파악하겠다!'라는 열정은 잠시 내려놓고, 정말 편한 마음으로 가볍게 읽어 보기를 권장합니다.

읽기만 하면 재미가 없으니 각 글의 소제목을 따서 마인드 맵으로 그려 보세요. 웹 페이지의 헤딩 요소, 즉 <h1>과  <h2>, <h3>  요소만 따서 마인드 맵 도구로 트리 구조를 그려 보세요. 반복하다 보면 저자가 내용을 어떻게 논리적으로 구분하고 전개하는지 보입니다. 이것이 익숙해지면 글쓰기를 시작할 때 목차, 즉 ToC(Table of Contents)를 구성하여 뼈대를 잡아 놓고 글 쓰는 것이 쉬워집니다. 이 부분을 여러분께 숙제로 드립니다.

CLOVA 문서 중 알람 처리하기 가이드의 목차(ToC)

바쁘다

참 신기합니다. 화장실에 들어가서 대소사를 치르며 웹툰 볼 시간은 있고, 자기 전에 핸드폰 붙잡고 하등 쓸모없는 내용을 브라우징할 시간은 있는데 왜 운동할 시간은 없을까요? 그렇습니다, 제 얘기입니다. 사실 우리는 진짜 바쁩니다. 마음이 바쁘고 머리가 바쁩니다. 어쩌면 귀찮다기보다는 속이 너무 분주해서, 글을 쓰려고 앉아도 머릿속엔 까마귀 한 마리가 까악까악하고 지나갈 뿐이라서 손가락이 움직이지 않는 것일 수도 있습니다.

저자가 묵상해 본 글 쓸 시간이 없는 이유

우리가 아무리 바빠도 하는 일들을 떠올려 봅시다. 오늘은 밥 먹을 시간이 없어 굶었더라도 내일은 밥을 먹는 것 혹은 숨을 쉬는 것, 눈을 깜박이는 것. 요즘에는 출근 시간이 아무리 늦었어도 마스크를 챙겨 나오지 않았다면 다시 집에 들어가 마스크를 챙겨 나오거나 근처 상점에 들러서라도 마스크를 사서 착용하는 것, 사랑꾼이라면 사랑하는 가족에게 사랑한다고 표현하는 것, 사랑하는 정인과 눈을 맞추는 것. 이런 일들은 아무리 바빠도 즐겁게 하겠지요? 결국 아무리 바빠도 하는 일은 반드시 해야만 하는 일이거나 내가 애정을 가진 일입니다.

테크니컬 라이터 처방 - 바쁜 그대에게

누구나 자기가 하고 싶은 일만 하며 살 수 있으면 참 좋을 텐데 그렇지 못함을 우리 모두 잘 알고 있습니다. 그렇다면! 글 쓰는 것을 해야만 하는 일이나 애정 하는 일로 만들어 버립시다. 많은 개발 프로젝트에서 문서가 필수 산출물로 지정되는 일은 잘 없습니다. 깨어 있는 개발자들이여! 문서를 프로젝트의 필수 산출물로 넣읍시다! 물론 그보다 좋은 방법은 글쓰기를 좋아하는 일이나 즐거운 일로 만드는 것이겠죠. 사람은 다른 사람을 도울 때 보람을 느낍니다. 여러분이 일하면서 알게 된 좋은 팁이나 신입 사원이 알면 좋을 정보, 혹은 동료들에게 도움이 될 정보를 짧게나마 글로 남겨 공유해 보세요. 누군가에겐 정말 큰 도움이 될 수도 있습니다. 

숙제를 드립니다

귀찮고 어렵고 바빠서 글쓰기가 부담스럽지만, 그럼에도 불구하고 오늘을 계기로 변화를 꿈꾸는 '글린이' 여러분께 숙제를 드립니다. 

작문이 고민되는 그대에게

작문이 고민되는 그대에게 드리는 숙제입니다. 아래에서 하나 골라 도전해 보세요.

A. 오늘 코딩한 내용을 한 문장으로 작문해 보세요. 첫날은 문장 하나만 작성하세요. 이튿날은 두 개 작성해 보세요. 이렇게 늘려가 보세요. 그리고 작성한 것을 소리 내 읽어보세요.

B. 오늘 구현한 것이 없다면 최근 설치한 프로그램의 설치 가이드를 작성하세요. 시작을 돕기 위해 아래와 같이 가이드에 포함 시킬 내용 몇 가지를 알려 드립니다. 작성 후, 프로그램 제작자가 제공하는 설치 가이드와 비교해 보세요.

  • 프로그램에 대한 간략한 소개
  • 프로그램을 설치하기 위해 필요한 최소 사양
  • 프로그램 설치 방법
  • 프로그램 실행 방법

C. 내가 다니는 회사 혹은 개발하는 제품을 가족(부모님, 배우자, 자녀 등)에게 소개하는 글을 작성해 보세요. 이후 가족의 피드백을 받아 보세요. 그들이 정확하게, 완전히 이해하셨나요?

문서 구성이 고민되는 그대에게

문서에 어떤 내용을 넣어야 하는지, 목차는 어떻게 구성해야 하는지 고민이 되는 그대에게 드리는 숙제입니다.

A. 소프트웨어 플랫폼이나 제품의 개발자 사이트의 문서 섹션이 어떤 페이지들로 구성돼 있는지 다음과 같이 목차를 만들어 보세요.

B. 문서를 하나 선택해서 해당 문서를 구성하는 소제목만 옮겨 적어서 다음과 같이 목차를 만들어 보세요. 다음은 CLOVA 문서 중 음원 재생 처리하기 가이드의 목차입니다.

CLOVA 음원 재생 처리하기 가이드 목차

이 작업을 여러 문서를 대상으로 반복해서 수행해 보세요. 꼭 마인드 맵으로 그릴 필요는 없고 다음과 같이 단순한 목록 형태로 작성해 보셔도 됩니다. 

음원 재생 처리하기

  • 음원 재생하기
  • 음원 재생 경과 보고하기
  • 음원 재생 제어하기
    • 음원 정보 관리하기
    • 음원 정보 업데이트하기
  • 음원 맥락 정보 작성하기

어떤 문서를 골라야 할지 고민된다면 다음 목록에서 사이트를 하나 선택해 수행해 보세요.

May peace be on earth and unto you

이 글을 쓰고 나니 언젠가는 '그것이 알고 싶다 - 왜 테크니컬 라이터는 개발자의 글을 못마땅해 하는가?'도 심층 분석해 보고 싶군요.

개발자는 본인이 구현한 것이 무엇을 하는지는 물론 본인이 구현한 것을 제3자가 어떻게 사용할 수 있는지를 설명할 줄 알아야 한다고 생각합니다. 여러분 모두 이 능력을 키워 차곡차곡 쌓아가는 개발자가 되시길 응원합니다. 계획한 대로 보내지 못한 2020년이었지만 이제 곧 그 막이 내리고 새로운 장이 펼쳐집니다. 여러분의 2021년 계획에 '글 잘 쓰는 개발자가 되자!'가 포함되기를, 그래서 제가 드린 숙제에 도전해 보시길 기대합니다.

어드벤트 캘린더는 성탄절을 기다리며 하루하루를 세는 달력입니다. 이 글이 여러분을 만나는 날 며칠 후는 성탄절입니다. 성탄절의 진정한 기쁨이 여러분에게도 충만하길 바랍니다. 이 글로 여러분 마음에 '할 수 있다'는 포부와 평안이 가득 차기를, 그리고 여러분과 여러분이 쓴 글을 읽을 독자의 안녕을 바랍니다. 메리 크리스마스!