나만의 개발 문서 작성법
모든 기록은 도움이 된다
왜 문서화를 해야 할까?
새로운 팀원의 합류
새로운 팀원이 합류를 했을 때, 바로 우리의 팀으로 적응한다면 최고의 시나리오다. 하지만 사실상 그럴 수는 없다.
어떻게 일을 하고 있고, 어떤 툴을 사용하고 있는지, 어디에 코드가 작성되어 있는지, 어떤 구조로 되어 있는지, 왜 이러한 기술을 사용했는지 등 기존까지의 회사 히스토리가 있을 것이다. 기존까지의 모든 히스토리를 알지 못한다면 바로 적응하기란 쉽지 않다.
물론 처음 들어왔다면, 어떠한 한 분이 옆에서 도와주겠지만 하루 종일 옆에서 도와줄 수는 없다. 또한, 새롭게 합류한 팀원도 부담스러울 수 있다.
그렇기 때문에 우리는 새로운 팀원이 합류를 했을 때 쉽게 적응할 수 있도록 하는 문서를 작성해야 한다. 문서를 보면서 새로운 팀원도 스스로 회사 및 업무에 대해 파악할 시간을 주고, 궁금한 점을 정리해서 물어봄으로써 새로운 팀원의 부담을 줄여주고 기존 팀원의 시간을 잘 활용할 수 있다.
그렇다고 새로운 팀원만을 위한 일은 아니다. 계속해서 일을 해오던 팀원들에게는 당연시 해오던 것들이 새로운 사람의 시각에서 봤을 때는 이상하거나 잘못된 부분이 보일 수 있다. 이러한 점을 기존 팀원들에게 말해줌으로써 못 보고 있던 부분을 수정할 수도 있다.
개발 작업 로그
한 명의 개발자가 개발을 한 후, 결과가 잘 나오고 에러가 없다면 당장은 문제가 없다. 하지만 그 후가 문제다.
서비스 에러가 발생했는데, 그 한 명의 개발자가 휴가를 갔거나 퇴사를 했다면 어떻게 할 것인가? 물론 기존의 팀원이 어떻게든 에러를 막겠지만, 많은 시간을 소비해야 한다. 만약 개발을 어떻게 진행했는지에 대한 문서가 있었다면, 에러를 수정하는 데 있어 큰 도움이 되었을 것이다.
또한 결과가 잘 나오고 에러가 없다고 해서 그 과정이 모두 맞는 것은 아니다. 다른 분들이 봤을 때, 더 좋은 방법이 있을 수 있다. 물론 개발하는 과정에서 어려운 부분이 있었을 때 물어보고 구글링의 도움을 받아 더 좋은 방법을 찾아냈겠지만, 그 과정을 문서화하고 공유함으로써 도움을 줬던 사람도 제대로 도움을 준 것인지 확인을 할 수 있고 다른 개발자도 해당 기능이 어떻게 개발을 했는지 문서를 통해 알 수 있다.
자신의 자산
위에서 작성한 문서화를 해야 하는 이유들을 읽고, 남을 위해 문서화를 해야 한다고 생각할 수 있다. 물론 남을 위해도 맞지만 자신을 위해서도 필요하다.
어떤 업무를 진행하다 "아... 이거 분명히 예전에 했었는데..." 또는 "예전에 발생했던 오류인데.." 등 예전 발생하고 해결했던 내용들을 기억하지 못할 수 있다. 이럴 때 자신이 작성했던 문서가 있다면, 빠르게 문서를 찾고 쉽게 문제를 해결할 수 있다.
경험해 본 결과 내가 해놓은 기록은 기억하기 쉽다.
모든 이유를 종합해 보자면, 문서화를 해야 하는 이유는 커뮤니케이션 리소스를 줄일 수 있다는 것이다. 다른 사람과의 커뮤니케이션 또는 자신과의 커뮤니케이션 리소스를 줄일 수 있다는 것이 내가 생각하는 가장 큰 문서화의 장점이자 문서화를 해야 하는 이유다.
나는 어떻게 문서화를 하고 있는가?
나의 비즈니스 파트너 Notion
나의 노트북에는 항상 Notion이 실행되어 있고, 나와 같이 일을 한다.
개발을 함에 있어 오류가 발생하고 코드를 수정하는 경우가 많다. 오류가 발생했을 때 Google에 검색한 후 오류 해결 방법을 찾고 오류를 해결하고 다른 작업을 진행하는 경험을 한 적이 있을 것이다. 사실 나도 Notion 을 만나기 전까지는 그랬던 것 같다.
하지만 Notion 을 만난 후, 오류가 발생했을 때 해당 오류 코드를 우선 Notion에 복붙하고, 오류 해결에 있어 도움이 된 자료 링크를 같이 복붙한다. 이렇게만 해놔도 다음에 많은 도움이 되었다.
더 도움이 되는 방법은 복사해 놓았던 내용들을 정리하는 것이다. 나는 오류 관련 정리를 아래 3가지 챕터로 나눈다.
오류 상황
오류 원인
해결 방법
"오류 상황"은 내가 복붙해 놓은 오류 코드가 될 것이다. 가능하면 어떻게 행동했을 때 해당 오류 코드가 발생했는지 작성해 주면 더 좋다. ex) build 명령어를 입력했는데 이와 같은 오류가 발생함.
"오류 원인"은 해결을 하다 보면 자연스럽게 알게 된다. 왜 이러한 오류가 발생했는지에 대해 솔직하게 작성하면 된다. '솔직하게'가 키포인트다. 부끄러워하지 않았으면 좋겠다. 내가 작성한 오류 원인에는 "오타" 단 2글자도 적혀있는 것도 있다.
"해결 방법"은 당연히 해결한 방법을 작성하면 된다.
추가로 개발을 진행하면서 Version1 코드를 복사해 놓고, 다음에 수정을 한다면 Version2 코드도 우선 노션에 복붙해 놓기도 한다. 이렇게 함으로써 스스로 "왜 처음에 이렇게 생각하지 못했을까?"라는 생각을 해볼 수 있다. 많이 사용하지는 않고, 가끔씩 사용하는 방법이다.
이렇게 오류 관련 문서만 작성한 후, 소제목에 "작업 로그"라고 적으면 개발 관련 문서가 생성된다. 여기에 조금 더 느낌 있는(?) 문서를 작성하고자 한다면, "왜 이 작업을 해야 하는가?" and "작업 목표"를 작업 로그 앞에 작성해 주고, "마무리" and "TODO"를 작성해 주면 더 느낌 있어진다.(개인적인 생각임다.)
내 고민을 좀 들어줘!
개발을 진행하다 보면 개발을 하기 전에 많은 고민을 하게 된다. 나는 이러한 고민하는 시간을 줄이기 위해서 시작한 방법이 고민(=생각)을 글로 작성한다.
내가 어떤 생각을 하고 있는지에 대한 것을 생각이 아닌 글로 보면 도움이 될 때가 많았다. 그리고 하나하나 고민에 대한 답을 작성하다 보면 생각보다 내가 했던 고민은 쉽게 해결이 된 경험이 있다.
나는 이러한 고민을 최대한 문서에 남기려고 한다. 그 이유는 단순하다. 나중에 다른 사람이 봤을 때 해당 개발을 진행했던 사람은 어떤 고민을 했는지 알 수 있고, "왜 이렇게 개발했을까?"에 대한 답을 줄 수도 있다.
또한, 같은 개발을 하더라도 시니어 분들은 주니어가 어떤 부분에서 고민하는지 알 수 없다. 하지만 주니어 입장에서도 고민 하나하나를 시니어에게 물어가며 작업을 진행할 수 없다.
고민을 글(=문서)로 작성하고 공유하면 그 문서를 본 시니어는 "주니어 입장에서는 이런 부분이 고민일 수 있겠구나!"라고 생각할 수 있고, 주니어는 "나만 그런 게 아녔구나...!"라는 생각을 하면서 서로 공감할 수 있다.
마무리
생각보다 간단하게 문서를 작성한다고 생각했지만, 문서를 작성하고 공유하는 행동을 개발 팀원분들께서 좋게 봐주셨다. 그렇기 때문에 이러한 글을 작성하게 되었는데 이 글을 읽은 개발자분들 또한 다른 사람에게 도움이 되는 글을 작성해 주시면 좋겠고, 이 글도 다른 사람들에게 많은 도움이 되면 좋겠슴다:)
