[TOOL-011][실무] 처음 보는 사람도 따라 하는 README 쓰기
페이지 정보
본문
[이번 수업]
README는 저장소를 처음 연 사람이 프로젝트의 목적과 실행 방법을 이해하도록 돕는 첫 문서입니다. 독자를 정하고, 확인한 명령과 예상 결과를 적고, 긴 설명은 별도 문서로 연결하는 방법을 배웁니다. 마지막에는 필요한 항목이 빠졌는지 작은 코드로 확인합니다.
[선수지식]
TOOL-004의 Git 저장소와 커밋, TOOL-010의 비밀정보 관리, CORE-011의 공식 문서 확인 방법을 알고 있으면 좋습니다.
[학습목표]
1. README에 목적, 준비 조건, 실행, 예시, 도움받는 방법을 구성합니다.
2. 복사 가능한 명령에 실행 위치와 예상 결과를 함께 적습니다.
3. 링크·이미지·문제 해결 문장을 이해하기 쉽게 작성합니다.
[핵심개념]
문서를 쓰기 전에 독자를 한 문장으로 정합니다. 처음 사용하는 사람이라면 “무엇을 하는가, 왜 필요한가, 무엇을 준비하는가, 어떻게 실행하는가, 실패하면 어디를 보는가” 순서가 자연스럽습니다. 유지보수자에게는 구조, 테스트, 배포, 변경 규칙도 필요합니다. 한 문서에 모두 넣지 말고 README에는 시작에 필요한 내용만 두고 상세 설계와 기여 방법은 docs 폴더로 나눕니다. 같은 저장소의 파일은 docs/setup.md 같은 상대 링크로 연결하면 복제한 환경에서도 이동하기 쉽습니다.
좋은 예제는 시작 디렉터리, 필요한 버전, 설치·실행 명령, 입력과 예상 출력을 포함합니다. “설정하세요”보다 파일 이름, 바꿀 값, 성공 확인 방법을 적습니다. 문제 해결은 “증상 → 확인 명령 → 원인 → 해결 → 정상 결과” 순서로 쓰면 찾기 쉽습니다. 기능이 바뀌면 코드와 문서를 함께 갱신하고 깨끗한 환경에서 절차를 다시 실행합니다.
Markdown은 #으로 제목 계층을 만들고 명령은 코드 블록으로 구분합니다. 제목 단계는 순서대로 쓰고 링크 문구는 “여기”보다 “설치 절차”처럼 목적을 드러냅니다. 이미지에는 핵심 정보를 설명하는 대체 텍스트를 적습니다. 큰 표가 좁은 화면에서 읽기 어렵다면 목록으로 바꿉니다.
[따라하기]
아래 내용을 README.practice.md로 저장하세요.
# 온도 변환기
섭씨를 화씨로 바꾸는 연습용 명령줄 프로그램입니다.
## 준비
Python 3.10 이상이 필요합니다.
## 실행
python app.py 20
예상 출력: 68.0 F
## 문제 해결
명령을 찾을 수 없으면 python --version으로 설치와 버전을 확인합니다.
다음 코드를 check_readme.py로 저장합니다.
from pathlib import Path
required = ("# 온도 변환기", "## 준비", "## 실행", "## 문제 해결")
text = Path("README.practice.md").read_text(encoding="utf-8")
missing = [heading for heading in required if heading not in text]
print("문서 확인: 통과" if not missing else "빠진 항목: " + ", ".join(missing))
두 파일을 같은 폴더에 둡니다. macOS와 Linux에서는 python3 check_readme.py, Windows PowerShell에서는 py check_readme.py를 실행합니다. 예상 결과는 문서 확인: 통과입니다. “## 문제 해결”을 지우고 다시 실행하면 빠진 항목이 표시됩니다. 경로와 UTF-8 인코딩을 명시했으므로 세 운영체제에서 같은 방식으로 확인할 수 있습니다.
[흔한 실수]
프로젝트 이름만 적고 실행 조건이나 예상 결과를 생략하지 마세요. 자신의 컴퓨터에서만 통하는 절대 경로, 설치되지 않은 명령, 오래된 화면을 남기기 쉽습니다. 제목을 글자 크기 용도로 건너뛰거나 한 문단에 여러 작업을 섞으면 찾기 어렵습니다. 코드 변경 뒤 문서 갱신을 미루면 설명과 동작이 어긋납니다.
[보안 주의]
공개 문서와 예제에는 실제 비밀번호, API 키, 쿠키, 내부 주소, 개인정보, 운영 로그를 넣지 않습니다. 비밀값은 YOUR_API_KEY처럼 분명한 가짜 값으로 표시하고 안전한 저장 방법을 설명합니다. 외부에서 복사한 sudo 명령이나 다운로드 후 바로 실행하는 명령은 출처와 내용을 확인하지 않은 채 안내하지 마세요. 오류 예시는 식별 정보를 지우고 재현에 필요한 정보만 남깁니다.
[직접 해볼 과제]
연습 README에 “## 사용 예”를 추가해 입력 0의 예상 출력 32.0 F를 적으세요. 검사 코드의 required에도 같은 제목을 추가한 뒤 통과와 실패 결과를 기록합니다. 상세 설치 문서를 docs/setup.md에 둔다고 가정하고 목적이 드러나는 상대 링크 한 줄도 작성하세요.
[확인문제]
1. 처음 사용하는 사람을 위한 README의 핵심 항목 세 가지는 무엇인가요?
2. 실행 명령 옆에 버전과 예상 결과를 적어야 하는 이유는 무엇인가요?
3. 같은 저장소의 긴 문서를 상대 링크로 연결하면 어떤 점이 좋은가요?
[다음 학습]
다음 차례인 PY-011에서 자동 테스트로 문서에 적은 동작을 계속 검증합니다. TOOL 트랙에서는 TOOL-012에서 새 컴퓨터에서도 재현되는 개발환경을 만듭니다.
[공식 참고 자료]
저장소 README 안내
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
Markdown 기본 작성 문법
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
CommonMark 명세
https://spec.commonmark.org/current/
W3C 링크 목적 접근성 설명
https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html
Diátaxis 문서 구조 안내
https://diataxis.fr/
README는 저장소를 처음 연 사람이 프로젝트의 목적과 실행 방법을 이해하도록 돕는 첫 문서입니다. 독자를 정하고, 확인한 명령과 예상 결과를 적고, 긴 설명은 별도 문서로 연결하는 방법을 배웁니다. 마지막에는 필요한 항목이 빠졌는지 작은 코드로 확인합니다.
[선수지식]
TOOL-004의 Git 저장소와 커밋, TOOL-010의 비밀정보 관리, CORE-011의 공식 문서 확인 방법을 알고 있으면 좋습니다.
[학습목표]
1. README에 목적, 준비 조건, 실행, 예시, 도움받는 방법을 구성합니다.
2. 복사 가능한 명령에 실행 위치와 예상 결과를 함께 적습니다.
3. 링크·이미지·문제 해결 문장을 이해하기 쉽게 작성합니다.
[핵심개념]
문서를 쓰기 전에 독자를 한 문장으로 정합니다. 처음 사용하는 사람이라면 “무엇을 하는가, 왜 필요한가, 무엇을 준비하는가, 어떻게 실행하는가, 실패하면 어디를 보는가” 순서가 자연스럽습니다. 유지보수자에게는 구조, 테스트, 배포, 변경 규칙도 필요합니다. 한 문서에 모두 넣지 말고 README에는 시작에 필요한 내용만 두고 상세 설계와 기여 방법은 docs 폴더로 나눕니다. 같은 저장소의 파일은 docs/setup.md 같은 상대 링크로 연결하면 복제한 환경에서도 이동하기 쉽습니다.
좋은 예제는 시작 디렉터리, 필요한 버전, 설치·실행 명령, 입력과 예상 출력을 포함합니다. “설정하세요”보다 파일 이름, 바꿀 값, 성공 확인 방법을 적습니다. 문제 해결은 “증상 → 확인 명령 → 원인 → 해결 → 정상 결과” 순서로 쓰면 찾기 쉽습니다. 기능이 바뀌면 코드와 문서를 함께 갱신하고 깨끗한 환경에서 절차를 다시 실행합니다.
Markdown은 #으로 제목 계층을 만들고 명령은 코드 블록으로 구분합니다. 제목 단계는 순서대로 쓰고 링크 문구는 “여기”보다 “설치 절차”처럼 목적을 드러냅니다. 이미지에는 핵심 정보를 설명하는 대체 텍스트를 적습니다. 큰 표가 좁은 화면에서 읽기 어렵다면 목록으로 바꿉니다.
[따라하기]
아래 내용을 README.practice.md로 저장하세요.
# 온도 변환기
섭씨를 화씨로 바꾸는 연습용 명령줄 프로그램입니다.
## 준비
Python 3.10 이상이 필요합니다.
## 실행
python app.py 20
예상 출력: 68.0 F
## 문제 해결
명령을 찾을 수 없으면 python --version으로 설치와 버전을 확인합니다.
다음 코드를 check_readme.py로 저장합니다.
from pathlib import Path
required = ("# 온도 변환기", "## 준비", "## 실행", "## 문제 해결")
text = Path("README.practice.md").read_text(encoding="utf-8")
missing = [heading for heading in required if heading not in text]
print("문서 확인: 통과" if not missing else "빠진 항목: " + ", ".join(missing))
두 파일을 같은 폴더에 둡니다. macOS와 Linux에서는 python3 check_readme.py, Windows PowerShell에서는 py check_readme.py를 실행합니다. 예상 결과는 문서 확인: 통과입니다. “## 문제 해결”을 지우고 다시 실행하면 빠진 항목이 표시됩니다. 경로와 UTF-8 인코딩을 명시했으므로 세 운영체제에서 같은 방식으로 확인할 수 있습니다.
[흔한 실수]
프로젝트 이름만 적고 실행 조건이나 예상 결과를 생략하지 마세요. 자신의 컴퓨터에서만 통하는 절대 경로, 설치되지 않은 명령, 오래된 화면을 남기기 쉽습니다. 제목을 글자 크기 용도로 건너뛰거나 한 문단에 여러 작업을 섞으면 찾기 어렵습니다. 코드 변경 뒤 문서 갱신을 미루면 설명과 동작이 어긋납니다.
[보안 주의]
공개 문서와 예제에는 실제 비밀번호, API 키, 쿠키, 내부 주소, 개인정보, 운영 로그를 넣지 않습니다. 비밀값은 YOUR_API_KEY처럼 분명한 가짜 값으로 표시하고 안전한 저장 방법을 설명합니다. 외부에서 복사한 sudo 명령이나 다운로드 후 바로 실행하는 명령은 출처와 내용을 확인하지 않은 채 안내하지 마세요. 오류 예시는 식별 정보를 지우고 재현에 필요한 정보만 남깁니다.
[직접 해볼 과제]
연습 README에 “## 사용 예”를 추가해 입력 0의 예상 출력 32.0 F를 적으세요. 검사 코드의 required에도 같은 제목을 추가한 뒤 통과와 실패 결과를 기록합니다. 상세 설치 문서를 docs/setup.md에 둔다고 가정하고 목적이 드러나는 상대 링크 한 줄도 작성하세요.
[확인문제]
1. 처음 사용하는 사람을 위한 README의 핵심 항목 세 가지는 무엇인가요?
2. 실행 명령 옆에 버전과 예상 결과를 적어야 하는 이유는 무엇인가요?
3. 같은 저장소의 긴 문서를 상대 링크로 연결하면 어떤 점이 좋은가요?
[다음 학습]
다음 차례인 PY-011에서 자동 테스트로 문서에 적은 동작을 계속 검증합니다. TOOL 트랙에서는 TOOL-012에서 새 컴퓨터에서도 재현되는 개발환경을 만듭니다.
[공식 참고 자료]
저장소 README 안내
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
Markdown 기본 작성 문법
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
CommonMark 명세
https://spec.commonmark.org/current/
W3C 링크 목적 접근성 설명
https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html
Diátaxis 문서 구조 안내
https://diataxis.fr/
- 이전글[PY-011][실무] pytest로 자동 테스트 시작하기 26.09.05
- 다음글[CS-011][실무] 자주 쓰는 코드 설계 패턴 고르기 26.09.05
댓글목록
등록된 댓글이 없습니다.