StudyDad

문서화와 인수인계 시리즈 5/9프로젝트 문서에 용어집이 필요한가?처음에는 과해 보일 수 있다. CORS, Lambda, CloudFront, API Gateway 같은 용어는 검색하면 정의가 나온다. 공식 문서도 있고, 블로그 글도 많다.하지만 프로젝트 안에서의 용어집은 일반 사전과 역할이 다르다.일반 사전은 "무엇인가"를 설명한다.프로젝트 용어집은 "이 프로젝트에서 왜 중요한가"를 설명한다.문제 상황운영 콘솔 문서를 정리하면서 여러 기술 용어가 반복해서 등장했다.CORSpreflightAPI GatewayLambda Function URLLambda LayerCloudFrontCache TTLinvalidationSSO cookiewithCredentialsSource of Truthjob tablec..

문서화와 인수인계 시리즈 4/9아키텍처 결정 기록, 흔히 ADR이라고 부르는 문서는 거창해 보인다. 대규모 조직이나 플랫폼 팀에서나 쓰는 문서처럼 느껴질 수도 있다.하지만 작은 운영 도구를 만들 때도 ADR은 필요하다.이유는 단순하다. 시간이 지나면 왜 그렇게 만들었는지 잊어버리기 때문이다.코드는 최종 결과만 보여준다. 하지만 그 결과에 도달하기까지의 선택지, 제약, 포기한 것, 다시 검토해야 할 조건은 코드에 남지 않는다.문제 상황운영 콘솔을 만들면서 여러 결정을 내려야 했다.React SPA를 어디에 배포할 것인가API 앞에 Gateway를 둘 것인가Lambda만 쓸 것인가, 상주 서버도 둘 것인가RDB를 둘 것인가, 파일 기반 저장소로 충분한가오래 걸리는 엑셀 생성은 동기 API로 처리할 것인가CO..

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

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

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