StudyDad

문서화와 인수인계 시리즈 3/9프로젝트 문서를 정리하다 보면 모든 내용을 README에 넣고 싶어진다. 가장 눈에 잘 띄고, 새로 들어온 사람이 먼저 열어보는 파일이기 때문이다.하지만 운영 중인 시스템에서는 README 하나로 충분하지 않다. 개발 시작을 돕는 문서, 시스템 구조를 설명하는 문서, 운영 인수인계를 위한 문서는 목적이 다르다.문서가 목적별로 나뉘지 않으면 두 가지 문제가 생긴다.첫째, README가 너무 길어져 아무도 끝까지 읽지 않는다.둘째, 중요한 운영 정보가 개발 가이드 사이에 묻힌다.세 문서의 차이가장 단순하게 나누면 이렇다.문서주요 독자답해야 하는 질문README처음 실행하는 개발자어떻게 설치하고 실행하는가아키텍처 문서구조를 이해하려는 개발자시스템이 어떻게 나뉘어 있고 왜 그런가H..

문서화와 인수인계 시리즈 2/9인수인계 문서를 쓰려고 하면 막막하다. 무엇을 어디까지 적어야 할지 애매하다. 너무 적으면 쓸모가 없고, 너무 많이 적으면 아무도 읽지 않는다.운영 시스템의 HANDOVER는 목적이 분명해야 한다. 새 담당자가 시스템을 이해하고, 배포하고, 장애를 확인하고, 위험한 변경을 피할 수 있어야 한다.이 글은 운영 콘솔을 정리하면서 사용한 HANDOVER 문서 구조를 일반화한 것이다.1. 시스템 개요문서의 시작은 기술 스택이 아니라 시스템의 목적이어야 한다.예를 들어 다음 질문에 답한다.이 시스템은 누구를 위한 것인가어떤 업무를 처리하는가내부 사용자만 쓰는가, 외부 사용자도 보는가데이터 원천은 어디인가운영상 가장 중요한 기능은 무엇인가좋은 개요는 한 문단으로 시스템을 설명할 수 있..

문서화와 인수인계 시리즈 1/9프로젝트를 넘겨줄 때 가장 먼저 떠올리는 문서는 보통 README다. 설치 방법, 실행 방법, 폴더 구조, 주요 명령어를 적는다. README는 중요하다. 하지만 실제 운영 중인 시스템을 넘겨줄 때 README만으로는 부족하다.운영 중인 시스템에는 코드 밖의 정보가 많다. 어디에 배포되어 있는지, 어떤 API가 어떤 저장소를 보는지, 장애가 나면 어떤 로그를 봐야 하는지, 배포할 때 어떤 파일을 건드리면 안 되는지, 특정 기능이 느릴 때 어디부터 확인해야 하는지 같은 정보다.이런 정보는 코드만 읽어서는 바로 알기 어렵다. 그래서 인수인계 문서는 코드 설명서가 아니라 운영 지도여야 한다.문제 상황운영 콘솔 두 개를 정리하면서 비슷한 문제가 보였다.하나는 외부 입력과 공개 페이..