책표지
발표를 듣기전 나의 생각들
“테크티컬 라이팅이 무엇인가. 그리고 왜 해야하는가.” 에 대한 답을 찾아가자.
- 남정현 연사
- 예상 독자 : 포트폴리오를 작성하는 취준생, 내가 만든 코드를 공유해야하는 주니어 개발자
- 기대 효과 : 글을 쓸 때, 구조에 대해서 알게된다.
- 주의사항 : 이 글은 강연을 듣고, 개인(필자) 스타일로 재해석한 글이라, 많은 부분이 강연과는 관련 없을 수 있다.
참여하게 된 계기
이번엔 어떤 행사에 참여할까 고민하면서 ”festa” 를 탐험하던 와중, “한빛미디어” 가 눈에 들어왔다.
일단 구매하고 생각했다.
1) 한빛미디어라는 출판사에 대한 신용
2) 2)요즘 나의 관심사인 문서화(Documentation)
위 두 가지 이유로 참석했다.
강연해주신 분은, 이 책과 연관성은 없으신 것 같다.
(직무가 동일하다는 점을 제외)
문서화를 하지 않으면, 몸이 두 개도 모자를 것이다.
“문서화를 하지 않으면, 몸이 두 개도 모자를 것이다.”
이 문장은 내가 생각한 내용이다.
평소에 위처럼 느끼고 있다. 나의 일을 자동화하는 것에 요즘 관심이 많다. 나는 모바일 앱 개발자이다. 그러다보니, 배포와 테스트를 자동화 하는 것 그리고 코드 생성이 자동화 대상이다. code_runner 니 Xcode Cloud 니, GitHubAction 를 사용하여 문제를 해결한다. 그러다 보면 하나가 아쉽다. 정성적인 업무나 환경상 자동화 툴을 사용할 수 없는 업무는 해결할 방법이 없을까? 그 고민에 대한 해결책이 나는 “문서화” 라고 생각한다.
업무 인수인계: 문서로
만약 어떤 기획자가 신입부터 열심히 일단위 서비스 매출 통계 정리를 보고해왔다고 가정하자. 그런 그에게 1 년이라는 시간이 흘렀다. 그리고 후임이 들어왔다. 그 기획자는 선임이 되면서, 더 많은 그리고 다른 일을 해야했다. 그래서 후임에게 일단위 서비스 매출 통계 정리 를 위임하려고 한다. 이 때, 어떤식으로 업무를 알려주고 싶은가.
1) “말로 전달해야 아주 디테일한 설명까지 할 수 있어. 이게 피드백도 바로바로 되고 시간도 짧고 얼마나 좋아.”
2) “내가 지금 말로 전달하더라도, 듣는이가 100% 이해할 수는 없어. 그리고 까먹으면 나에게 또 물어볼텐데, 그때마다 알려주는게 더 큰 커뮤니케이션 비용이야. 문서로 작성해서 주자.”
사실 위 사례에서는 1번이든 2번이든 큰 문제가 되진 않는다. 그런데, 이게 조직이 커진다고 생각해보자. 그리고 내가 회사에서 업무를 하나만 하는 것이 아니다.
선택은 자유지만, 가능하면 2버..ㄴ
나를 위해, 그리고 전달받는 이를 위해, 문서화는 좋은 해결책이다.
요즘은 LLM 기술덕택에 이 문서화가 언젠가 챗봇 형태로 변경될 날이 올지도 모르겠다.
문서화를 하면, 두 번 설명할 정보의 양이 줄어든다. 그리고 지식전달의 퀄리티 관리에 유용하다. 만약 조금 일하고 많이 쉬는 것을 좋아한다면 문서화가 좋은 방법이다.
신입의 질문이 만약 문서로 된 것이 없다면, 문서화가 필요한 시점
문서화를 하지 않으면, 몸이 많아야한다. 회사를 다니면서, 그런 경험 있지 않은가? 나는 신입인데, 이 회사에 대해서 아는게 하나도 없다. 좋은 회사라면 OT 정도 진행해주겠지. 그렇더라고 현업의 일을 하려고 한다면 모르는 것들 투성이다. 그 무거운 분위기 속에서 선임에게 질문을 한다는 것은 어려운 일이다. 나는 이 당시 속으로 별별 생각을 다했다. ”사회의 차가움이 바로 이런 것인가…“, ”집에 간다고 할까?“ 등
무거운 분위기에서 새로운 신입이자 팀원에게 한 줄기 빛은 바탕화면에 설치된 하나의 문서일 수 있다.
“000주식회사 온보딩 가이드”
혹은 돔황챠!!
군대는 생각보다 온보딩이 잘 되어 있는 조직
잠깐 다른 경험에 대해서 이야기하면, 군대이야기를 해볼까 한다. 군대는 이미지가 아주 수직적이고 권위주의적일 지 모른다. 그런데, 시스템은 이보다 친절할 수가 없다. 만약 독자분이 군대에 군인으로 입대하면 아래와 같은 일이 벌어진다.
- 자동화된 배치 시스템 : 내가 어디로 가야할지, 어디서 근무할지 고민할 필요가 없다. 자동으로 처리된다.
- 배치 전, 행정 처리 시스템 진행 : 인사담당자가 행정적인 처리를 내가 고려하지 않더라도 처리해준다. 혹시 병으로 근무하셨다면, 내가 특정 공간에 발령이 났는지 확인하고 가는 일은 있을 수 없다.
- 적응 기간 부여 : 군대에 처음온 사람들을 위하여 군대 시스템이 무엇인지 훈련기간을 통해 알려준다. 그리고 충분한 체력을 길러줘 앞으로 있을 일에 대해 그릿을 길러준다. 이 부분은 직업군인도 마찬가지이다. 새로운 부대에 배치 받는 중대장이라면, 이전에 연락처를 받을 수도 있고, 하루 이틀 전에 가볼 수도 있다. 그리고 여러 가지 인수인계 자료를 받고 인수인계 기간을 공식적으로 지정해준다. 그리고 인수인계를 받는다. 혹은 함께 일하는 기간도 존재한다.
- 문서화 하지 않더라도 퇴사하지 않는 직원 : 부사관들은 해당 지역에서 별일 없으면 계속 근무한다. 그 분들은 이 부대와 지역에 대한 히스토리를 잘 알고 있다. 그래서 맥락을 언제든 물어볼 수 있다.
이렇게만 보면, 군대라는 조직은 온보딩에 상당히 좋다. 실제로 좋다. 그리고 위 과정이 하나도 빠짐없이 문서화가 되어 있다. 그 문서 하나만 없어져도, 군부대에서 난리가 날 정도니까.
다시 회사에 새로 합류한 신입의 상황으로 돌아가보자.
이런 과정이 없다. 그러면 나는 질문이 생기면, 선임에게 물어봐야 한다. 자꾸 물어보니까 선임이 귀찮아 한다. 눈치가 보인다. 회사가 싫다. 출근하기 싫다. 그렇게 퇴사한다…
농담반 진담반으로 논리적 비약을 했다. 하지만, 반은 진담이다. 사소한 것이 나를 위로하기도 하지만, 사소한 것이 나를 가장 힘들게 하기도 한다.파스칼이 말함
(강연 내용 공유용) 지식부채
3 가지 부채에 대해서 설명해주셨다.
- 자본금 : 투자자에게 빌린 부채
- 기술 : 당장의 편리함을 추구하고자, 공학적인 손해를 감수하는 부채
- 지식 : 당장의 편리함을 추구하고자, 문서화 되지 않은 암묵지 형태의 지식
“지식부채” 라는 것이 구체적으로 무엇일까?
내가 경험해본 지식부채 중 제일 힘들게 만드는 것이, 아무리 추론해도 맞출 수 없는 지식부채이다. 예를들면, 어느 회사에서도 A 라는 방식으로 처리하지 않지만, 특정 회사만 A 라고 처리해서, 누군구 알려주지 않으면 절대 모르는 지식을 의미한다.
이렇게 문서화되지 않고, 구두로만 전달되는 지식은, 임직원이 많아질수록 커뮤니케이션 비용이 커질 것이다.
(강연 내용 공유용) 글을 잘쓰는 간단한 3 단계와 5 가지 노력
여기서 강연자분이 소개해주신 방법을 나열해보겠다.
글을 잘쓰기 위한 3 단계
1. 예상독자 설정(독자분석)
2. 시나리오분석
3. 문제점에 대한 해결책을 제시
글을 잘쓰기 위한 5 가지 노력
1. 좋은 표현들을 읽고 듣는다.
2. 비문학적 글쓰기를 한다.
3. 기억이 안난다.
4. 테스트를 한다.(검토하라는 말이겠지)
5. 시각적으로도 청각적으로도 정보를 전달한다.
위에 좋은 말씀이지만, 개인적으로는 책에 있는 내용을 추천한다. 왜냐하면, 위에 설명해주신 방법은 일반화된 내용이라, 구체적인 행동으로 실천단계에서 분명이 서로 다른 방향으로 진행될 것이다.
반면에 책에서는 양식을 준다. 해당 양식을 바탕으로 내가 써보는 노력을 하는게, 바로 당장 실천해볼 수 있는 방법이라 추천한다. 고민할필요 없이 그냥 그 양식맞추면됨
강연과 책을 읽고, 나에게 남은 것
내가 강연과 책을 경험하고 남은게 무엇인지 곰곰히 생각해봤다.
- 문서화를 해야하는 정당성
- 문서화는 내가 만든 어플리케이션에 대한 API
- 문서작성과 코드작성의 유사성
그리고 다시 생각해봐야할 만한 강연에서의 한 구절
제품이 안좋으면 문서도 좋을 수 없다.
개인적으로는 제품은 제품대로 문서는 문서대로 작성할 수 있다곤 생각하지만, 그것은 아주 피상적인 레벨일 것이다. 진짜 좋은 문서를 작성하려고한다면, 제품이 좋아야 할 것이다.
제품의 실행까지 10 단계로 구성된 제품보다 1단계로 구성된 제품이 문서도 깔끔하지 않겠는가.
회고
나는 어떤 행동에 대한 정량화가 중요하다고 생각한다. 그래야 피드백이 가능하다. 피드백을 떠나서, 기본적으로 엔지니어라고 한다면, 정량적 측정은 기본이다.
정량적으로 측정하기 위해서는 어떤 지표를 만들어야하고 그 지표는 특정 개념에 대한 정의로 부터 나온다. 그러면 그 정의는 어디에 적어둘 것인가. 그게 바로 문서라고 생각이 된다.
문서 위에 나의 정량적인 개념들을 나열하고, 설명한다. 그리고 그 문서를 전달한다. 피드백받으며 개선된다. 새로운 문서가 만들어진다.
이 책에 좋은 내용들이 많은데 내가 아직 오픈소스 README 를 작성해볼 경험이 없어서 이해하지 못한 부분이 있는 것이 아쉽다.
