개발자에게 “개발 문서 꼭 써 달라” 말했습니다

10분

2024.12.24.

문제 제기: 문서 작업 좋아하세요?

저 역시 개발자로 일할 때, 빠듯한 개발 일정과 귀찮음으로 문서 작업에 소홀했던 기억이 납니다. 어떤 프로젝트에서는 PM의 강요에 못 이겨 프로젝트가 끝나고 나서야 모든 개발 산출물을 한 번에 작성한 경험도 있고요. 그 당시 저는 항상 궁금했습니다. 과연 누구를 위해 문서를 만들고 있는지, 이렇게 만든 문서를 나중에 누가 읽고 업데이트나 할지 말이죠.

최근 “개발자들이 싫어하는 것 TOP 10(Top 10 Developer Hates)”이라는 흥미로운 블로그 글을 보았습니다. 예상했지만 문서 작업은 고객 요구 사항 변경, 업무 방해, 미팅, 나쁜 코딩에 이어 다섯 번째를 차지했습니다.

왜 대부분 개발자는 문서 작업을 좋아하지 않을까요? 여러 채널로 개발자들의 다양한 의견을 수집하고 종합해 보니, 크게 세 가지 이유로 정리할 수 있었습니다.

시간 소모와 비효율

일반적으로 대부분 개발자의 우선순위는 당연하게도 개발(코딩) 업무입니다. 새로운 기능을 개발하거나 문제를 해결하는 일, 흔히 말하는 ‘본업’에 집중하고 싶어 하죠. 문서 작업은 우선순위가 낮은 업무로 인식하여 시간 낭비라고 생각할 수 있습니다. 또한 문서 작업 자체를 비효율적이라고 생각할 수 있고요. 코드를 보거나 주석을 통해 개발 관련 내용을 이해할 수 있는데 문서를 작성하라고 하니 비효율적인 추가 업무라는 생각밖에 안 드는 것이죠.

글쓰기 기술 부족

글쓰기 자체를 어렵게 생각하는 개발자들도 많은 것 같습니다. 비단 개발자뿐만 아니라 많은 사람이 문서 작성에 익숙하지 않습니다. 특히 개발자들은 코드 작성에는 익숙하지만, 글을 체계적으로 작성하거나 많은 사람에게 공유하는 데에는 부담을 느낄 수 있습니다. 이에 따라 문서 작성 자체를 어려운 과정으로 생각하는 듯합니다. (저도 이 기고 글을 작성하면서 동일한 느낌을 받고 있습니다.)

효용성에 대한 의구심

시간을 들여 작성한 문서가 실제로 업무에 얼마나 쓰일지 확신이 없는 경우, 효용성에 대한 의구심이 들 수 있습니다. “무플보다는 악플이 더 낫다.”라는 말이 있습니다. 힘겹게 문서를 작성하더라도 동료나 나 자신이 제대로 활용하지 않는다면, 일회성의 형식적인 업무로 끝나고 맙니다. 꾸준히 문서 작성을 해야 할 동기를 약화할 수 있습니다.

전환점: 우리는 문서 없이 일할 수 없어요!

아이러니하게도, 제가 다른 개발팀과 협업이나 프로젝트를 시작할 때 가장 자주 듣는 말은 “문서가 있으면 공유해 줘.”입니다. 우리는 알고 있습니다. 문서 작성을 좋아하지는 않아도, 개발 문서는 필요하다는 것을 말이죠.

개발자로 일하던 시절을 돌이켜 보면, 당시 팀에는 어떠한 문서도 존재하지 않았습니다. 그래서 모든 정보는 처음 시스템을 개발한 선임들의 기억과 경험 속에만 존재했습니다. 레거시(Legacy) 코드에 대한 문서가 없다면 결국에는 사람 자체가 문서의 역할을 합니다. 이 사람들에게 의존하여 제품을 운영하거나 개발할 수밖에 없는 상황이 많았습니다. 또한, 문서 없이 입에서 입으로만 지식이 공유되다 보니 예기치 못한 오해와 잘못된 개발로 많은 사고(Incident)가 발생했고요.

소프트웨어는 사람들의 눈에 보이지 않습니다. 그런 만큼 코드를 작성한 개발자의 생각을 읽어야 하는 언어라고 생각합니다. 따라서 정리된 문서를 보지 않고는, 다른 개발자가 작성한 코드를 이해하는 데 시간이 많이 들어갑니다. 심지어 시간이 지나면 작성한 본인도 코드를 이해하기 어려워집니다. 결국 문서 작성은 본인의 지식을 정리하고 관리하는 가장 기본적인 방법으로, 다른 사람과의 협업을 위한 가장 중요한 자료임에는 틀림 없습니다.

아이디어: 어떻게 문서 작성을 독려할 수 있을까요?

시간 소모, 비효율, 그리고 효용에 대한 의구심 같은 부정적인 이유는 결국 기존 문서 작성의 경험에서 비롯한 문제라고 생각합니다. (글쓰기 기술 부족처럼 스킬이 필요한 부분은 예외입니다.)

따라서 이 문제를 해결하려면, 문서 작업이 “시간을 투자할 만큼 가치 있으며, 협업을 위해 코드와 같이 관리해야 할 주요 업무다.”라는 인식을 줄 수 있어야 했습니다. 자연스레 개발자들을 “동기부여”할 방법들을 알고 싶었습니다.

이곳저곳, 다양한 사례들을 검색하다 우버의 문서 작업 문화에 대한 아티클을 읽었습니다. 여기에서 개발자의 문서 작업을 동기부여할 본질적인 아이디어를 얻을 수 있었죠. 우버는 어떻게 개발자의 문서 작업 문화를 만들까요? 우버의 3가지 접근법을 간략히 정리해 보았습니다.

첫 번째, 동기부여 문화 장려하기(Cultivating motivation)

우버는 “팀뿐만 아니라 나의 커리어 발전을 위해 문서 작성은 중요하다.”라는 슬로건과 함께, 꾸준히 문서 작업을 장려한다고 합니다. 또, “그저 보여주기 위해 기록하는 것이 아니라 특정 문제를 해결하기 위해 기록한다”는 메시지와 함께, 문서화에 열정적인 관리자와 직원을 찾아내 그들이 글쓰기 관리자 역할을 하도록 격려합니다. Doc Stars(양질의 문서를 만들고 업데이트하는 동료)를 선정해 그들이 문서화에 긍정적 영향을 끼치도록 지원합니다.

두 번째, 교육 제공하기(Providing education)

모든 개발자와 매니저들은 온보딩에서 필수로 Technical Communication Course에 참석해야 합니다. 여기서는 효과적으로 문서를 작성하는 방법보다는 문서화의 중요성 인식을 위한 트레이닝 위주로 수행합니다. 특히, “누가 볼 것이고”, “무엇이 이슈였고”, “어떻게 해결했는지”, 세 가지를 항상 문서에 포함해 독자로 하여금 공감을 끌어낼 문서를 만들게 하도록 강조합니다.

세 번째, 문서 작업에 대한 마찰 줄이기(Reducing tooling friction)

우버는 개발자들이 문서를 작성하는 데 있어 생기는 여러 마찰을 줄일 가이드를 제공합니다. 개발자들이 문서를 작성하는데 머뭇거리게 할 수 있는 요소들로는 문서 중복 가능성, 위치의 부정확함, 공개 여부 등이 있습니다. 이를 최대한 관리해 시작에 자신감을 가질 수 있도록 만든 것입니다. 특히, 문서의 초안은 유연하게 작성하지만, 게시할 때는 모두가 볼 수 있는 일관된 위치로 이동해야 한다고 합니다.

실행하기: “왜 해요?”에서 “어떻게 해요?”로

우버의 3가지 접근법을 통해 문서 작업은 1) 팀을 넘어 나 개인의 커리어 발전을 위한다는 이해를 가지고 2) 독자의 공감을 이끌 수 있는 내용을 (문제 해결을 중점으로) 포함하여 3) 문서 작성의 허들이 없도록 지속해서 관리하며 4) 많은 사람이 보고 피드백 줄 수 있는 문화를 만드는 것이 핵심이라는 인사이트를 도출했습니다.

스스로 “문서 작업은 왜 해야 하지?”라는 질문에서 벗어나게 되었으니, 어떻게 팀에 적용할 수 있을지 같이 논의하며 실행해 보고 싶었습니다. 우버의 사례로 얻은 4가지 인사이트를 실행할 액션 아이템을 팀 내 개발자 동료들과 협의 및 도출했고, 4가지 단계로 진행해 보았습니다.

Step 1. 문서 작업의 중요성 공감하기

개발자들은 여전히 문서 작업을 회의적으로 여깁니다. 하지만 우버의 사례를 보여 주니, 문서 작업이 팀 내 지식 공유뿐만 아니라 개인의 발전에도 도움이 된다는 점에 어느 정도 공감을 보였습니다. 이에 문서 작업을 하나의 액션 아이템으로 관리하자 협의했습니다. 하지만 처음에는 다른 우선순위에 밀리고 시간적 여유가 없다는 이유로 번번이 완료되지 못했습니다.

몇 번의 회고(Retrospective) 세션을 거쳐, 결국 물리적인 시간 확보와 지속적인 관리가 함께하지 않는다면 똑같은 실패가 반복될 것이라 의견이 모아졌습니다. 그에 따라 분기별 주요 개발 및 우선순위를 계획하는 세션에서, 프로덕트 담당자를 포함해 모두의 문서 작업을 우선순위 중 하나로 인식시키며 문서 작성 시간을 따로 확보했습니다. 나아가 문서 작업을 공식 업무의 하나로 포함해 개발 완료의 조건으로 선정할 것을 협의했습니다.

Step 2. 함께 문서 포맷 디자인하기

토의 과정에서 가장 많이 논의한 것은 문서 작업을 위한 공통 포맷이었습니다. 문서를 올리는 위치, 문서 형식과 내용, 문서를 보는 사람 등 공통 표준을 함께 만들어 보기로 했습니다. 무엇보다 컴팩트한 템플릿을 통해 최대한의 정보를 전달할 방법들을 논의하였습니다.

템플릿을 제작할 때는 우버의 Doc Stars와 같이, 팀 내 문서화를 잘하는 개발자들의 지원과 관리를 받았습니다. 또, 양질의 좋은 참고 문서들을 보며 저희 스쿼드만의 공동 템플릿을 구성하였습니다. 이를테면, 개발 시작 전에는 지라 백로그에 모두가 개발 목적을 이해할 수 있도록, 1) 비즈니스 유스 케이스 2) 시스템 영향도 3) 개발 배경(목적) 4) 예상 시나리오 등 필수 항목을 꼭 기술하도록 했죠.

Step 3. 많은 사람이 볼 수 있는 문서로 홍보하기

개발자 입장에서 이용자가 많이 사용하지 않는 기능을 개발하는 것만큼 가치 없고 슬픈 일은 없을 겁니다. 마찬가지로 누구도 읽지 않는 문서는 지속 가능한 문서 작업 문화에 나쁜 영향을 끼칠 수 있습니다.

그래서 가능한 많은 사람에게 내용이 드러나며 상호작용 할 수 있도록 사내 위키 페이지(컨플루언스)에 하나의 섹션을 만들었습니다. 모두가 이 공간에 포스팅(Posting)을 하며, 여러 사람과 리뷰와 코멘트를 주기적으로 공유하였습니다.

Step 4. 성과를 위한 아이템으로 제안하기

마지막으로 위키 메인 페이지에 Top 10 기여자 항목을 만들었습니다. 문서 작업을 많이 해 팀에 많은 가치를 준 작성자를 꾸준히 노출하며 동기부여를 줄 수 있도록 하였습니다.

그뿐만 아니라, 문서 작업에 대한 기여를 팀의 지식 공유와 협업을 위한 개인 KPI로서 인지하고 평가할 것을 매니저들에게도 지속해서 제안하였습니다.

마치며

여전히 문서 작업 문화를 구성해 나가는 과정은 순탄하지 않습니다. 일부 개발자들은 본업인 개발 업무 이외 일정 시간을 문서 작업에 소요하는 것에 불만을 표현하며 형식적으로 템플릿만 채워 넣고 있죠. 하지만 적어도 지금은 모두가 백로그의 목적, 이번 개발이 어떤 가치를 제공할지에 대해서는 의문을 가지지 않습니다. 또한, 문제 해결 과정을 축적한 문서화된 지식이 개발자들의 업무 이해와 확장에 많은 도움이 되고 있다는 사실에 감사하고 있기도 합니다.

물론 반강제적인(?) 요청으로 시작한 일이지만, 함께 사례를 찾고, 템플릿을 만들고, 다른 나라 개발자들과 피드백을 주고받고, 다양한 생각과 아이디어들을 공유하는 과정을 거치니, 단순히 “문서 작성을 해야 해!”라는 당위성을 넘어 “왜 해야 하지?”에 대한 공감이 나왔습니다. 그 덕분에 긍정적인 문서 작업 문화와 프로세스를 구성할 수 있었다고 느낍니다. 앞으로도 문서 작업이 지금 일, 나아가 커리어에 어떤 영향력을 가질 수 있는지 몸소 경험하고 느낄 문화를 만들기 위해 다양한 아이디어를 시도해 보고자 합니다.

로그인하고 자유롭게 의견을 남겨주세요.