배경 및 목적
- 문서를 작성하는 것이 어려움.
- 글을 쓴다는 것에 대해 배운적이 없음.
- 문서를 잘 작성하고 싶음.
나만 작성하기 어려운가?
- 문서자료 작성과 관련된 글을 찾다보니, 대부분의 글에서 보이는 문장.
- 대부분의 엔지니어가 코드를 작성하고, 이용하고, 유지 보수하는 업무와 관련한 대표적인 불만이 양질의 문서 자료가 부족하다는 것.
- 현실적으로 대부분의 문서자료는 우리가 스스로 작성해야 함.
- 문서작성이 잘 안되는 이유?
- 문서자료가 중요하다는건 모두가 알지만, 문서자료가 제공하는 이점이 무엇인지 이해를 못하고 있다.
- 문서자료의 작성을 프로그래밍과 별개의 기술로 본다.
- 글쓰기에 자신이 없다.
- 유지보수할 대상이 하나 더 늘어난다.
- 문서자료는 일반적으로 작성자에게 혜택이 돌아가지 않는다.
문서자료란?
- 엔지니어가 작업을 끝마치기 위해 작성하는 모든 텍스트.
- 별도의 문서(PRD, TDD, Jira, Confluence, etc..) 및 코드의 주석등이 포함됨.
- 구글 엔지니어가 작성하는 문서자료의 대부분은 코드 주석.
문서자료의 중요성
- 조직의 규모가 커질수록, 개발자들이 맡은 역할이 점점 더 구체적이고 복잡해짐.
- 일관된 정보 제공과 공유가 매우 중요함.
- 구두로 설명할 경우, 중요 정보가 누락되거나 틀린 정보가 제공될 수 있음.
문서자료에 담겨야 하는 내용
- 누가, 무엇을, 언제, 어디서, 왜
- 누가: 문서를 봐야할 사람
- 언제: 문서가 생성되고, 리뷰되고, 갱신된 날짜
- 어디에: 문서가 존재해야할 장소
- 대부분의 기술문서는 어떻게 에 대한 답변만 있음.
- 이건 어떻게 동작하죠?
- 이 API 를 어떻게 사용하죠?
- 서버 설정을 어떻게 하죠?
- 무엇과 왜도 어떻게 만큼 중요함.
- 무엇은 문서의 목적을 말함
- ex) 이 문서는 order 서버를 테스트 환경에서 구동하기 위해 작성된 튜토리얼입니다.
- 무엇 을 작성하면 문서를 적절하게 구성하는데 도움이 됨.
- 무엇 과 연관없는 내용이 적혀 있다면 해당 내용을 별도 문서로 옮기라는 신호임.
- 왜 는 문서의 목적을 설정함.
- 원래 기대한 바를 잘 작성 했는지를 확인할 수 있음.
문서자료를 잘 쓰기 위해선
- 서투른 글도 일단 쓴다.
- 잘 쓴 글도 아무런 도움이 안될 수도 있고, 서투른 글도 누군가에겐 도움이 될 수 있다.
- 머릿속에서 떠도는 생각을 체계화 할 수 있다.
- 일단 쓰여지면, 개선할 수 있다.
- 최소한 작성자에게는 도움이 된다.
- 왜 를 생각하자.
- 문서 자료를 만드는 이유를 항상 생각해야 한다. 그 이유를 벗어난 내용은 아무리 좋아도 불필요한 내용이다.
- 자기 객관화를 할 수 있다.
- 글 쓰기도 일의 일부다.
- 일 하고 남은 시간에 쓸려고 하니, 글 쓸 시간이 없다고 느끼는 것.
- 문서자료는 업무를 설명하고, 중요한 정보를 전달하기 위한 것으로 문서자료를 작성하는 것 자체가 일의 일부.
- 업무 시간에 글을 쓰자.
- 혼자만의 오답 노트에서 벗어나자.
- 오답 노트의 특징
- 대부분 남의 이야기
- 다른 사이트에서 복붙한 내용
- 특정 기술에 대한 자료 모음
- 나만 알아볼 수 있다.
- 피드백이 없다.
- 글을 작성하면, 리뷰를 요청해서 의도적으로 피드백을 받자.
- 다른 사이트의 내용, 특정 기술에 대한 자료를 복붙했으면, 최소한 실행결과 라도 추가하자.
- 열린 마음으로 리뷰하자
- 문서자료에는 작성자의 관점과 지식이 반영된다.
- 리뷰어의 생각이나 지식과 다른다고 비난 해서는 서로에게 도움이 되지 않는다.
- 열린 마음으로 피드백을 주고받으면 방어적인 태도가 줄어든다.
- 리뷰어의 피드백을 더 긍정적으로 받아들일 수 있다.
- 다른 관점과 지식을 문서에 포함시키는 데 도움이 된다.
마치며
- 문서 자료를 작성할때마다 막막함이 있다.
- 여전히 글을 쓰는건 어렵다.
- 같은 주제로 글을 10개 정도 쓰면 책 한권을 쓸 수 있다. 라고 한다.
- 머릿속 생각을 정리하기 위해서라도 꾸준히 써볼 생각이다.