저번주에 들어온 신입이 문서화를 하자고 했다

오랜만에 다시금 블로그를 쓰고있는 킴스캐슬입니다
10월 즈음부터 시작해서 그 동안 참 많은 일이 있었는데요

정말 힘들어 죽는줄 알았습니다

결론적으로는 iOS 신입 개발자로 취업을 하게되어서 회사를 다니고 있습니다
오늘로써 정확히 입사 한달차네요(0.083년차 개발자랄까요)

이렇게 말하고 보니 써야할 글감이 산더미네요ㅎㅎ... 취준 회고글도 써야하고 입사후 어떤걸 느끼고 배우고있는지 신입일기같은것도 한번 써보는것도 재미있겠다는 생각이 드네요

우선 오늘은 제목에서 알수있는 것처럼 문서화에 대한 이야기를 해보려고 합니다

문서화?

갑자기 뜬금없이 문서화를 주제로 가져와봤는데요. 평소에 제가 문서화에 관심이 많았냐고 하면 그건 사실 아닙니다. 문서화라고 할만한것들을 해본 경험이라고는 pr을 정말 자세히 쓰려고 노력하는 정도인것같아요

그도 그럴만한게 제가 지금까지 진행했던 프로젝트는 열이면 열 제가 프로젝트의 시작부터 팀원으로 개발을 진행했었기때문에 내가 대부분의 코드와 히스토리를 알고 있었거든요. 굳이 문서화로 기록을 남겨야하나라는 의구심이 들 수가 없는 환경에서 개발을 해왔습니다

하지만 제가 지금 회사에 신입 개발자로 입사했을 때, 가장 어려웠던 점을 하나 꼽으라면 망설이지 않고 기존 코드를 보면서 기능, 흐름, 정책을 파악하는 것이라고 말하지 않을까 싶습니다

뉴비가 새로운 게임에 입성했을때의 느낌이랑 비슷하지 않을까요

물론 기본적인 온보딩을 위한 문서나 서비스의 핵심 기능에대한 문서화는 잘되어있지만 코드자체의 흐름등에 대한 문서가 없어서 코드를 한줄 한줄 읽어가면서 파악을 해야했습니다

사실 코드를 보는거야 라이브러리를 뜯어보는게 습관이 되어서 그런가 그렇게 힘들지 않았었습니다. 다만 라이브러리는 대충 흐름을 파악하면 메서드를 사용만 하면 알아서 내부적으로 동작하는 경우가 많기에 사용자체에 큰 문제나 부하가 없었지만 회사는 다르죠 내가 이 코드를 수정하고 디벨롭 시켜서 버그를 잡거나 새로운 기능을 붙여야합니다

문서화가 필요하겠구나를 느낀 순간

입사하고 일주일정도 지난 시점에서 아주 쉬운 task를 맡았습니다. 대충 요약하자면 이렇습니다

"서버에서 기존에 주던 데이터에서 bool타입의 field를 하나 추가해줄겁니다. 그럼 킴스캐슬님은 false면 iOS기본 alert만 하나 띄워주세요"

처음에 task를 듣자마자 뭐야? 엄청 쉽잖아 서버작업만 끝나면 20~30분이면 끝나겠네라고 생각했었습니다. 그런데 이 task를 완료하는데 무려 이틀이라는 시간이 걸렸습니다. 당연히 이렇게 데이터가 흘러가겠지라는 생각이 100%틀렸음을 깨달았을때는 하루가 꼬박 지난 후였습니다

어찌저찌 해당 task를 마치고나서 이런 순간이 들었습니다

만약 새로운 개발자가 들어와서 우리 서비스에 대한 기본적인 데이터흐름에 대한 문서를 알고 있다면 이런 task를 더 빨리 끝낼 수 있지 않을까?

마침 신입 개발자이기도 하고 팀원분들이 코드를 보고 흐름을 파악하기 위한 시간과 여유를 주시기도 했고 이왕 내가 코드와 흐름을 판단하는 시간을 들이는김에 조금 더 시간을 들여 문서화를 해보기로 했습니다

뭐를 문서화 해야할까?

우선 제가 온보딩 기간에 문서화를 개인적으로 진행하면서 중요하게 여겼던건 세 가지 였습니다

1. flow chart혹은 이미지를 통해 흐름을 파악할 수 있는 시각화 자료 만들기
2. 특정 동작이 어떤 메서드를 통해 데이터가 전달되고 변경되는지에 대한 흐름을 함수단위로 정리하기
3. 내가 모르는 용어는 새로 들어오는 사람이 모를거라고 생각하고 설명 추가하기

위의 세가지를 중심으로 하나의 feature를 문서화하니 이정도 분량의 문서가 작성되었습니다(보안상 내용은 가렸습니다 ㅎㅎ...)

처음에는 feature에 대해서만 문서화를 진행하려 했는데 코드를 계속 보다보니 이런 생각이 들었습니다

A기능을 구현하게 된다면 이 B코드를 쓰면 되게 편하겠는데???

하지만 만약 B코드의 존재를 모른다면 메서드를 가져다 쓰는 10초면 끝날 작업을 1시간동안 코드를 구현한다고 시간을 날려버릴 수도 있겠다고 생각했습니다

그래서 우리프로젝트에는 이런걸 편하게 구현할수있는 기능들 메서드들 객체들이 있다는걸 함께 정리하기 시작했습니다. 우리 프로젝트에서만 쓰이는 용어도 이때 함께 정리하기 시작했습니다

내가 만든 문서가 실용적이 아닐지라도 문서화를 하면서 굉장히 많은 생각을 하게되었습니다

문서화를 하기 위해서는 해당 함수나 변수가 어떤 친구인지에대해 알아야합니다. 그러다보면 더 좋은 함수명과 더 좋은 구조에대한 아이디어를 떠올릴 수 있게됩니다. 누군가가 볼 수도 있는게 아니라 누군가가 보게될 문서를 위한 시선이 추가되니 읽기 쉬운 코드를 위한 개선을 조금씩이라도 하게되지 않을까라는 문서화의 긍정적인 효과에대해서 느끼기 시작했습니다

문서화 이거 꽤나 괜찮을지도...?

Why don't we "Documentation"?

하지만 저는 아직 입사한지 한달도안된 신입이고 제가 만든 문서는 public한 문서가 아닌 private 문서 정도로 제 노션에 고이 남겨질 녀석정도로 생각을 하고 있었습니다

입사하고 일주일이 지났을까요? 모바일 챕터 회고에 참여하게되었는데 팀이 성장하고 있는 상황이고 이에따라 인원수가 증가함에 따라 새로들어오거나 서로의 커뮤니케이션에서 병목이 발생하고 있다는 문제에 대해 논의하기 시작했습니다

팀원이 1~2명일때는 코드나 비하인드를 모두 알고 있기 때문에 큰 문제가 없었지만, 서비스가 많아지고 개발자가 많아지면서 특정 팀원에 의존성이 높아지고 새로운 팀원이 코드의 흐름을 이해하고 따라가는데 점점 더 큰 병목이 생기고 있었다는 이야기가 나왔습니다

팀이 성장해나가는데 있어서 겪고있는 성장통에 대한 이야기를 나눌 수 있었고 앞으로의 팀을 위해서 개발원칙을 정하는 시간을 가지게되었습니다

개발원칙을 정하면서 서비스의 확장, 개발팀의 인원증가에 따른 커뮤니케이션비용 증가에 따른 기존 리소스 관련 문서화에 대한 필요성이 언급되었고 앞으로 어떻게 문서화를 해나갈지에 대한 이야기를 나누게 되었습니다

아래의 내용은 iOS소프트웨어 개발원칙을 정하면서 문서화에 대해 나왔던 실제 내용을 기반으로 작성되었습니다

생각의 흐름 1 - 뭘로 해야할까요?

가장 먼저 정해야하는건 어떤걸로 문서화를 해야할지에 대해 정해야했습니다

당연히 가장 먼저 떠오른 녀석은 노선(notion)이었습니다. 실제로 팀내 온보딩 문서라던가 컨벤션 등은 이미 노션에서 작성이 되어있었습니다

사용법을 배우는데 리소스를 들일 필요도 없기도 하고 익숙한 방식이었지만 한가지 문제가 있었습니다. 바로, 노션문서화의 경우 템플릿을 강제화하기 어렵고 자유도가 높기때문에 정형화된 문서작성이 어렵다는 것이었습니다

물론 노션을 잘쓰고 좋아하시는분들이라면 저 가정에 반박을 하실수도 있겠지만 저는 공감이 되는 부분이었습니다. 제 경험상 노션은 결국 시간이 지날 수록 방치되는 경우가 많았거든요

그래서 노션이 아닌 다른 방식을 찾아야했습니다

생각의 흐름 2 - 품은 얼마나 들려나요?

회사는 동아리가 아닙니다
신규 기능을 개발하고 버그를 잡고 더 좋은 프로덕트 자체를 만들어나가는 것이 1순위 입니다

리팩터링하겠다고 문서화하겠다고 기능 개발을 멈춘다는건 말이안됩니다

즉, 문서화라는 리소스를 들이면서도 기존에 작업하던 작업시간에 영향을 끼쳐서는 안됩니다
물론 문서화는 리소스를 들여서라도 해야할만큼 미래를 위해선 중요한 작업이 맞지만 서비스의 기능적인 발전에 장애가 되어서는 안된다는 점에는 다들 공감을 헀습니다

즉, 팀원들이 적당히 부담이 되지 않는선에서 문서화를 조금씩 진행할 수 있는 방식이 필요했습니다

Swift-docC을 한번 써볼까요?

회의를 마치고 곰곰히 생각을 해봤습니다. 어떤도구를 통해서 문서화를 해야할까를 말이죠

생각을 하면서 코드를 보다가 간간히 적혀있는 주석을 보면서 문득, Swift docC이라는게 떠올랐습니다

단지 주석만 달면 swift의 공식문서처럼 문서를 자동으로 만들어주기때문에 뭔가를 배울 필요가 없었습니다. 주석다는법만 통일하면 동일한 형식의 문서를 자동으로 만들어주기 때문에 노션을 선택할 수 없었던 문제도 해결되었습니다

마침, 이전에 회의록을 보니 팀원분들이 주석을 잘달자고 이야기를 했던 기록을 보게되었고 다음 회의에서 조심스럽게 말했습니다

혹시 괜찮으시다면 Swift-docC으로 문서화를 해보는건 어떠신가요?

Swift-docC에 대해서 처음들어보시거나 존재여부정도만 알고계시는 분들도 계셔서 제가 알아본 장점에 대해 말씀드렸고 다행히 긍정적으로 검토해주셨습니다

제가 문서화 감독관을 해보겠습니다~!!!

제가 Swift-docC을 제안했을 때 팀원분들이 걱정했던건 결국 누군가가 문서화에 대해서 계속해서 상기시켜주는 사람이 필요하다는 것이었습니다

주석을 잘 달아야하는 Swift-docC특성상 pr을 merge하기전에 주석을 잘 달았는지를 매번 체크하지 않으면 이전과 다를게 없을거라는게 그 이유였습니다

결국, 강제적으로 이부분을 계속해서 끌고나갈 수 있는 요소가 필요하다고 생각했고 pr시 코드관련이 아닌 주석에대한 내용으로만 approve해주는 사람이 있었으면 좋겠다고 제안해주셨고 제가 이 부분을 맡아서 진행하기로 했습니다

추가적으로 Swift-docC의 사용법과 주석다는 법을 정리해서 공유하기로 헀고 팀내에서 사용하고있는 사내앱을 문서화해서 예시 문서도 만들고 공유해보기로 했습니다

그렇게 3개의 WWDC영상을 보고 예시문서를 만들면서 고민되거나 다같이 이야기를 해봐야하는 부분을 정리해서 공유하게되었습니다

(위 이미지는 제가 정리하고 공유한 swift-docc에 대한 내용입니다. 다음 포스팅은 위에서 정리한 Swift-docC의 사용법에 대한 내용이 되겠네요)

---

일주일의 시간이 흐르고...

팀에서 본격적으로 문서화를 진행한지 일주일정도의 시간이 흘렀습니다

pr이 올라올때마다 이건 이렇게 주석을 달아주세요 라던가 이 부분을 주석을 달아주세요라는 코멘트를 남길때마다 긴장을 하고 있지만요...

그래도 프로젝트에 통일된 주석이 달리고 기능별로 나아가는 서비스별로 문서가 착착 만들어지는걸 보면서 아직 갈길은 멀지만 계속해서 이런 문화를 유지시킬수있도록 노력해야겠다는 생각이 듭니다

---

오늘은 회사에서 겪은 시행착오와 깨달음을 바탕으로 문서화를 시작하게 된 이야기를 해봤습니다:)

신입 개발자로서 느낀 회사의 코드 흐름과 데이터 구조를 이해하는 어려움, 그리고 그것을 극복하기 위해 노력한 과정은 분명 많은 분들이 공감할 수 있는 부분이지 않을까 싶습니다. 특히, 팀 내에서 정보가 공유되고 효율적인 개발 문화를 구축하는 것이 얼마나 중요한지를 다시한번 느끼고 있습니다

문서화는 단순히 기록을 남기는 것이 아니라, 팀의 성장과 협업을 도울 수 있는 중요한 자산이라고 생각합니다. 또한, 이런 문화를 처음 도입하고 발전시켜 나가는 과정에 기여 할 수 있다는 사실이 큰 동기부여가 되고 있습니다ㅎㅎ

다음번에는 문서화를 진행하며 사용했던 Swift-docC의 활용법과 팀원들과 나눈 다양한 논의들을 더 자세히 다룬 포스팅으로 찾아오겠습니다.

그럼 20000!