이번주의 주된 과제는 '문서화'였다. 총 8개의 문서를 작성해보았는데,
구현 과정에서 문서랑 코드랑 왔다갔다 하면서 자주 업데이트를 하게 되었다.
완벽한 문서는 있을 수 없겠지만, 그래도 너무 익숙하지 않아서 힘들었다....
항해 추천인코드: NYFKU8
✍️ 이번 주 주제: 문서화
이번 주의 메인 과제는 '문서화’였습니다.
총 8개의 문서를 작성하며, 비즈니스 로직을 분석하고 명확히 표현하는 데 집중했습니다.
또 모든 문서가 일관적이도록 하기 위해서 노력했습니다.
🗂️ 과제 내용 요약
- STEP 03 - 분석
- 시나리오 요구사항 분석 및 문서 작성 (e.g. 시퀀스 다이어그램, ERD 등)
- STEP 04 - 실행
- Mock API 및 Swagger 문서 작성
- (선택 과제) API E2E 테스트 작성
📄 작성한 문서 목록
총 8개의 문서를 docs/ 디렉토리 내 .md 파일로 작성했습니다.
- 요구사항 명세서
- 유스케이스
- 정책 문서
- API 명세서
- ERD
- 클래스 다이어그램
- 상태 다이어그램
- 시퀀스 다이어그램
🛠 Mermaid 도입기
처음으로 Mermaid라는 도구를 써봤는데, 정말 강력했습니다.
Mermaid란?
Markdown 기반으로 플로우차트, ERD, 시퀀스 다이어그램 등을 코드로 그릴 수 있게 해주는 문서화 도구
회사에서는 이전까지 문서를 주로 Figma로 작성했었는데, 이미지로 저장 후 프로젝트에 넣다 보니 수정 시 다시 Figma를 열어야 했고, 최신화도 어렵고 귀찮은 작업이었습니다.
하지만 Mermaid는 Markdown 문서에서 바로 수정 및 커밋이 가능하기 때문에 문서 수정이 간편하고, 협업 시에도 효율적입니다.
이 좋은 걸 이제야 알았다니... 늦게나마 알게 돼서 다행입니다.
🧠 어려웠던 점과 해결 방법
❗ 가장 어려웠던 점
- 비즈니스 로직을 잘 몰라서 어떤 정책이 필요한지, 어떤 문서를 작성해야 하는지 감을 잡기 어려웠습니다.
✅ 해결 전략
- 큰 틀 → 작은 틀 순서로 접근
- 예) 요구사항 명세서 → API 명세서 → ERD → 시퀀스/상태 다이어그램
- 점점 비즈니스 로직이 눈에 들어오기 시작했고, 문서 작성 속도도 점차 빨라졌습니다.
🧪 Swagger와 E2E 테스트
Swagger나 E2E 테스트 코드는 처음 작성해봐서 익숙하지 않았지만,
문서화 덕분에 로직을 이해한 상태였기에 Mock API로 구현 자체는 무난하게 진행할 수 있었습니다.
💬 멘토의 한마디에서 얻은 인사이트
"문서화가 필요 없게 하는 것이 가장 좋다."
처음엔 문서화 과제 주간에 이런 말씀을 들어서 놀랐지만, 곧 이 말에 공감됐습니다.
문서는 결국 또 하나의 유지보수 대상이기 때문에, 코드만 보고도 이해할 수 있는 구조를 만든다면 가장 이상적이겠죠.
다음 프로젝트에서는 Plasma Markdown, Nestia 같은 자동 문서화 툴도 활용해보고 싶습니다.
👨💻 팀 코드리뷰 소회
1. 동시성 처리 문서화의 부족
팀원들의 문서를 살펴보면서 내가 놓친 부분들이 눈에 띄었는데,
그 중 가장 아쉬웠던 점은 동시성 처리에 대한 문서화가 부족했다는 점입니다.
사실 동시성 처리에 대해서 아직 잘 이해하지 못한 상태여서,
문서에서는 단순히 "동시성 처리가 필요하다" 정도로만 추상적으로 언급했었습니다.
2. 주문 생성 vs 결제 처리 - 서비스 분리 여부
또 하나 흥미로웠던 점은 서비스 분리 방식이었습니다.
저는 주문 생성과 결제 처리를 별도의 서비스로 분리했는데,
대부분 팀원들은 주문 서비스 하나에서 둘 다 처리하는 방식을 택하셨습니다.
제가 서비스 분리를 선택한 이유는 다음과 같습니다:
- 사용자가 결제를 나중에 진행할 수도 있다고 생각함
- 결제 도중 페이지 이탈이나 PG사 에러와 같은 예외 상황 발생 가능성 고려
따라서 저는 주문은 먼저 생성하고, 결제는 별도 절차로 처리하는 구조가 더 유연하다고 판단했습니다.
🎯 다음 주 목표 & 다짐
이번 주는 기본 과제와 심화 과제 모두 PASS!
다음 주에도 좋은 결과를 얻으려면
일요일~화요일까지 시간을 어떻게 쓰느냐가 핵심이라고 생각합니다.
- 화요일 전까지 기본 과제 마무리
- 남은 시간엔 심화 과제에 깊이 있게 집중
- 멘토링 전에 사전 학습과 질문 준비 철저히
지난주엔 준비가 부족해서 멘토링 시간 이후 아쉬움이 남았기에,
이번에는 훨씬 더 알차게 준비해보려고 합니다.
✅ 한 줄 회고
"문서를 작성하며 비즈니스 로직을 자연스럽게 이해했고, Mermaid 덕분에 협업 가능한 문서화 경험을 얻을 수 있었다.
이제는 코드만으로도 문서가 되는 구조를 꿈꾼다."
'항해+' 카테고리의 다른 글
| 항해+ 백엔드 코드 5주차 회고 : 동시성 처리(Concurrency Control) 과제 정리 – 데이터 정합성과 성능 동시 확보하기 (항해 부트캠프 할인코드 있음) (4) | 2025.08.09 |
|---|---|
| 항해+ 백엔드 코드 4주차 회고 (2) | 2025.08.02 |
| 항해+ 백엔드 코드 3주차 회고 (0) | 2025.07.26 |
| 항해+ 백엔드 코드 1주차 회고 (5) | 2025.07.12 |
| 항해 플러스 백엔드 9기를 시작하는 마음(항해 추천인코드 있음) (0) | 2025.07.05 |