왜 마크다운으로 업무 문서를 쓰는가
노션, Confluence, Google Docs 등 훌륭한 협업 도구가 많은데 굳이 마크다운을 쓰는 이유가 있습니다.
- 플랫폼 독립적: 어떤 서비스가 망하거나 요금 정책이 바뀌어도 내 문서는 그대로입니다.
- Git으로 버전 관리: 누가 언제 무엇을 바꿨는지 기록이 남습니다.
- 빠른 작성 속도: 마우스 없이 키보드만으로 서식을 적용할 수 있습니다.
- 검색 용이: 일반 텍스트 파일이라
grep, 파인더, VS Code 전체 검색이 잘 됩니다.
회의록 템플릿
회의록은 일관된 형식이 있어야 나중에 찾아보기 쉽습니다. 다음 템플릿을 팀 내 표준으로 쓰세요.
# 회의록 - [프로젝트명] 주간 동기화
**일시**: 2026-04-29 (화) 14:00 ~ 15:00
**장소**: 회의실 A / 온라인 (Google Meet)
**참석**: 홍길동, 김철수, 이영희
**작성**: 홍길동
---
## 안건
1. 지난 주 작업 리뷰
2. 이번 주 목표 설정
3. 블로커 공유
---
## 논의 내용
### 1. 지난 주 작업 리뷰
- 홍길동: 로그인 API 완성, 테스트 코드 작성 중
- 김철수: 디자인 시스템 1차 완료, 피그마 공유함
- 이영희: 기획서 v2 작성 완료, 검토 요청
### 2. 이번 주 목표
- [ ] 로그인/회원가입 프론트엔드 연동 (홍길동, ~5/2)
- [ ] 대시보드 컴포넌트 개발 시작 (김철수, ~5/3)
- [ ] 사용자 인터뷰 3건 진행 (이영희, ~5/2)
### 3. 블로커
- 결제 API 연동이 외부 업체 승인 대기 중 → 이영희가 다음 주까지 팔로우업
---
## 결정 사항
- 배포 주기: 격주 금요일로 고정
- 코드 리뷰는 PR 올린 후 24시간 내 완료
## 다음 회의
**2026-05-06 (화) 14:00**주간 보고서 템플릿
주간 보고서는 상사나 이해관계자에게 진행 상황을 공유하는 문서입니다. 핵심만 간결하게 담으세요.
# 주간 보고서 - 2026년 18주차 (4/28 ~ 5/2)
**작성자**: 홍길동
**팀**: 프론트엔드
---
## 이번 주 완료
- [x] 로그인 API 연동 및 에러 처리
- [x] 사용자 프로필 페이지 레이아웃
- [x] 크로스브라우저 테스트 (Chrome, Safari, Firefox)
## 다음 주 계획
- [ ] 대시보드 차트 컴포넌트 개발
- [ ] 성능 최적화 (Lighthouse 점수 90+ 목표)
- [ ] 접근성 검토 (WCAG 2.1 기준)
## 이슈 / 블로커
| 이슈 | 심각도 | 조치 |
|------|--------|------|
| Safari iOS 사파리에서 날짜 picker 오류 | 중 | 대안 라이브러리 검토 중 |
| 백엔드 API 응답 속도 느림 | 저 | 백엔드 팀에 이슈 제기 완료 |
## 메트릭
- 완료 태스크: 8 / 10
- PR 머지: 5건
- 코드 리뷰: 7건프로젝트 기획서 구조
새 프로젝트를 시작할 때 빠르게 초안을 잡을 수 있는 구조입니다.
# [프로젝트명] 기획서
**버전**: 1.0
**작성일**: 2026-04-29
**상태**: 초안 / 검토 중 / 확정
---
## 배경 및 목적
(왜 이 프로젝트가 필요한가)
## 목표
- 정량 목표: ...
- 정성 목표: ...
## 범위 (Scope)
### In Scope (포함)
- ...
### Out of Scope (제외)
- ...
## 이해관계자
| 역할 | 담당자 | 책임 |
|------|--------|------|
| PM | 이영희 | 전체 조율 |
| 개발 | 홍길동 | 프론트엔드 |
| 디자인 | 김철수 | UI/UX |
## 일정
| 마일스톤 | 목표일 | 상태 |
|----------|--------|------|
| 기획 확정 | 5/10 | 진행 중 |
| 개발 완료 | 6/15 | 예정 |
| 출시 | 6/30 | 예정 |
## 리스크
| 리스크 | 확률 | 영향 | 대응 방안 |
|--------|------|------|-----------|
| 일정 지연 | 중 | 고 | 버퍼 2주 확보 |파일 관리 체계
문서가 쌓이면 찾기 어려워집니다. 처음부터 폴더 구조를 잡아두세요.
docs/
├── meetings/
│ ├── 2026-04/
│ │ ├── 2026-04-01-킥오프.md
│ │ └── 2026-04-15-주간동기화.md
│ └── 2026-05/
├── specs/
│ ├── 기능명세서-v1.md
│ └── API-설계.md
├── reports/
│ ├── 2026-04-weekly.md
│ └── 2026-05-weekly.md
└── decisions/
└── 2026-04-29-기술스택-결정.md특히 결정 기록(decision log)은 자주 간과되는데, 나중에 "왜 이걸 이렇게 했지?"라는 질문에 답하는 데 매우 유용합니다.
마크다운 업무 문서의 한계와 보완
모든 것이 장점만 있지는 않습니다.
- 실시간 협업 어려움: Google Docs처럼 여러 명이 동시에 편집하기 어렵습니다. → Git 브랜치 전략으로 보완하거나, 협업 시에는 HackMD, Notion을 병행하세요.
- 이미지 관리: 이미지 파일을 별도로 관리해야 합니다. → 저장소 내
assets/폴더를 만들어 같이 커밋하세요. - 기술 진입 장벽: 마크다운에 익숙하지 않은 팀원은 거부감을 느낄 수 있습니다. → 처음엔 이지 마크다운 같은 WYSIWYG 에디터로 시작하면 진입 장벽이 낮아집니다.
마크다운은 완벽한 도구가 아니지만, 가볍고 이식성 높은 문서 형식으로서 장기적으로 가장 안정적입니다. 중요한 문서일수록 특정 플랫폼에 종속되지 않는 형식으로 보관하는 것이 현명합니다.