[GitHub 100일 챌린지] Day 97 - 문서화 완성
100일 챌린지 Day 97 - 최종 프로젝트를 처음 보는 사람도 실행하고 이해할 수 있도록 문서를 완성합니다.
배울 내용
- README에 꼭 들어가야 할 항목
- 설치, 실행, 배포 방법을 재현 가능하게 쓰는 법
- GitHub 저장소를 포트폴리오처럼 보이게 정리하는 법
1. README는 프로젝트의 첫 화면이다
포트폴리오 프로젝트에서 README는 코드보다 먼저 읽힙니다. “무엇을 만들었는지”, “왜 만들었는지”, “어떻게 실행하는지”가 빠르게 보여야 합니다.
README를 읽는 사람은 보통 세 부류입니다.
| 독자 | 알고 싶은 것 |
|---|---|
| 채용 담당자 | 무엇을 만들었고 어떤 역할을 했는지 |
| 개발자 | 어떻게 실행하고 구조가 어떻게 되어 있는지 |
| 미래의 나 | 왜 이런 결정을 했고 다음에 무엇을 해야 하는지 |
따라서 README는 기능 소개와 실행 방법, 의사결정 기록을 균형 있게 담아야 합니다.
추천 구조:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 프로젝트 이름
한 문장 소개
## 주요 기능
- 기능 1
- 기능 2
- 기능 3
## 기술 스택
- Frontend:
- Backend:
- Deployment:
## 실행 방법
## 환경 변수
## 테스트
## 배포 링크
## 스크린샷
## 트러블슈팅
## 배운 점
2. 실행 방법은 그대로 따라 할 수 있어야 한다
좋은 문서는 추상적이지 않습니다. 명령어를 복사해서 실행할 수 있어야 합니다.
1
2
3
4
5
6
7
8
9
10
## 로컬 실행
```bash
git clone https://github.com/username/project-name.git
cd project-name
npm install
npm run dev
```
브라우저에서 `http://localhost:3000`을 엽니다.
패키지 매니저가 pnpm이나 yarn이면 실제 프로젝트와 맞춰 적습니다. 문서의 명령어와 저장소의 lockfile이 다르면 신뢰도가 떨어집니다.
실행 방법은 반드시 새 폴더에서 한 번 따라 해보세요. 이미 의존성이 설치된 내 개발 환경에서는 되지만, 처음 받는 사람에게는 실패할 수 있습니다.
확인 루틴:
1
2
3
4
5
git clone https://github.com/username/project-name.git
cd project-name
npm install
npm run dev
npm test
실패한 명령이 있으면 README에 전제 조건을 추가합니다. 예를 들어 Node 버전, 데이터베이스 준비, 환경 변수 필요 여부를 명확히 적어야 합니다.
3. 환경 변수 문서화하기
비밀값을 README에 직접 쓰면 안 됩니다. 대신 .env.example을 제공합니다.
1
2
3
4
# .env.example
DATABASE_URL=
GITHUB_TOKEN=
PUBLIC_SITE_URL=http://localhost:3000
README에는 의미와 발급 위치만 적습니다.
1
2
3
4
5
6
7
## 환경 변수
| 이름 | 설명 | 필수 |
| --- | --- | --- |
| `DATABASE_URL` | 데이터베이스 연결 문자열 | 예 |
| `GITHUB_TOKEN` | GitHub API 호출용 토큰 | 아니오 |
| `PUBLIC_SITE_URL` | 배포된 사이트 주소 | 예 |
환경 변수 문서에는 “예시 값”과 “실제 값의 저장 위치”를 구분하세요.
.env.example: 공개 가능한 키 이름과 예시 형식.env.local: 로컬 실제 값, Git에 커밋 금지- 배포 플랫폼 Secrets: 운영 실제 값
README에는 절대 실제 토큰, 비밀번호, 개인 계정 값을 넣지 않습니다.
4. 스크린샷과 배포 링크 추가하기
포트폴리오에서는 시각 자료가 중요합니다. 이미지가 있다면 실제 자산 경로를 사용하고, 없다면 배포 링크를 먼저 넣습니다.
1
2
3
4
5
6
7
8
## 데모
- 배포 URL: https://example.vercel.app
- GitHub 저장소: https://github.com/username/project-name
## 화면
없는 이미지를 임시로 링크하지 마세요. 깨진 이미지는 문서의 신뢰도를 크게 떨어뜨립니다.
5. 저장소 메타데이터 정리하기
GitHub 저장소 오른쪽 About 영역도 정리합니다.
- Description: 한 문장 소개
- Website: 배포 URL
- Topics:
portfolio,react,github-actions처럼 검색 가능한 태그 - README: 실행 방법과 배포 링크
- License: 공개 프로젝트라면 라이선스 명시
마지막으로 README 링크가 실제로 작동하는지 클릭해서 확인합니다.
6. 문서 품질 체크
문서를 다 썼다면 아래 관점으로 다시 읽습니다.
| 항목 | 질문 |
|---|---|
| 첫인상 | 10초 안에 프로젝트 목적이 보이는가 |
| 재현성 | 처음 받는 사람이 실행할 수 있는가 |
| 신뢰성 | 깨진 링크, 빈 이미지, 임시 문구가 없는가 |
| 보안 | 비밀 값이나 개인 정보가 없는가 |
| 맥락 | 왜 이 기술을 선택했는지 설명되어 있는가 |
특히 TODO, 나중에 수정, 임시, asdf 같은 표현이 남아 있으면 제출 전 제거하세요.
1
rg -n "TODO|나중에|임시|asdf|your-|example.com" README.md .env.example
예시 URL이 필요한 곳은 괜찮지만, 최종 포트폴리오 README에는 실제 배포 URL과 실제 저장소 링크를 넣는 것이 좋습니다.
정리
완료 체크:
- README에 프로젝트 소개와 주요 기능을 적었다
- 설치/실행/테스트 명령어를 실제 프로젝트와 맞췄다
.env.example과 환경 변수 설명을 추가했다- 배포 링크와 저장소 About 정보를 정리했다
- 깨진 이미지나 임시 링크가 없는지 확인했다
- 새 폴더에서 README 실행 방법을 따라 해봤다
- 비밀 값과 개인 정보가 문서에 없는지 확인했다
핵심 요약:
1
문서는 프로젝트의 사용 설명서이자 포트폴리오 첫인상이다. 처음 보는 사람이 실행할 수 있게 써야 한다.
다음: Day 98 - 배포 및 운영 →