Step 89. 마크다운 문서화 — 나만의 개인 위키

Level 1 — 프로그래밍과 컴퓨터 내부 | 난이도 ★☆☆☆☆ | 예상 소요 시간 2시간

전제: Step 47의 마크다운 기초, Step 86~88의 Git 사용법을 안다.

준비물: 텍스트 에디터와 Git Bash. 새로 배울 도구는 없습니다 — 마크다운, Git, GitHub, 이 셋을 "기록 시스템"으로 묶는 날입니다.
주의: 완벽한 문서를 목표로 하지 마세요. "6개월 뒤의 내가 검색해서 찾을 수 있는가"가 유일한 기준입니다.

잔인한 사실 하나를 알려 드리겠습니다. 6개월 뒤의 여러분은 지금의 여러분을 기억하지 못합니다. 지금 당장 떠오르는 "그 에러 어떻게 고쳤지?"도 세 달 뒤에는 백지가 됩니다. 보안 공부는 쌓는 양이 방대해서 이 문제가 다른 분야보다 빨리 찾아옵니다. 그래서 해커들에게는 오랜 격언이 있습니다 — 해킹 공부의 절반은 기록이다. 오늘부터 여러분은 "배우는 사람"이자 "기록하는 사람"입니다.

1. 학습 목표

이 챕터를 끝내면 다음을 할 수 있습니다:

마크다운 핵심 문법 일곱 개로 기술 문서를 작성한다
"한 줄 요약 / 실습 명령 / 막혔던 점"의 세 칸 구조로 개념 문서를 쓴다
에러 원문과 해결법을 트러블슈팅 문서에 기록한다
README 색인과 문서 간 링크로 위키 안을 오간다
"검색 가능성" 기준으로 문서를 점검하고 유지 규칙을 세운다

2. 배경 지식 — 오늘의 도구와 개념

오늘의 도구 한눈에 보기

구분	내용
언어·환경	마크다운 + Git Bash(버전 관리), GitHub(선택, 공개용)
오늘의 문법	제목(`#`), 인라인 코드(`), 코드 블록(```), 목록(`-`), 링크, 굵게, 인용
필요한 개념	제2의 뇌, 세 칸 문서 구조, 검색 가능성, README 색인
오늘의 산출물	Git으로 관리되는 개인 위키 저장소 `security-wiki`

2-1. 제2의 뇌 — 외울 것과 찾을 것의 분리

인간의 뇌는 "어디 있는지 아는 것"에는 강하고 "정확히 기억하는 것"에는 약합니다. 그래서 지식 관리의 핵심 원칙은 이것입니다 — 개념과 원리는 머리에, 명령어와 세부 절차는 위키에. 이 체계를 흔히 "제2의 뇌(second brain)"라고 부릅니다.

위키가 잘 만들어졌는지는 시험이 있습니다. "Wireshark에서 스캔 패턴만 골라내는 필터가 뭐였더라?"라는 물음에 30초 안에 답을 찾을 수 있으면 합격입니다. 검색이 먹히도록 평소에 내가 쓰는 단어로 적어 두는 것이 비결입니다.

2-2. 마크다운 복습 — 일곱 개면 충분하다

Step 47에서 배운 문법을 오늘의 작업 순서대로 다시 놓아 봅니다.

문법	쓰는 법	용도
제목	`#`, `##`, `###`	문서의 목차 뼈대
인라인 코드	`git status`	명령어 한 단어
코드 블록	```python	여러 줄 명령·코드
목록	`-`	절차 나열
링크	`[제목](주소)`	참고 자료·문서 연결
굵게	`<strong>중요</strong>`	경고·핵심 표시
인용	`>`	원문 인용

코드 블록을 열 때 python, bash처럼 언어 이름을 붙이면 GitHub에서 색이 입혀져 읽기 쉬워집니다. 이 일곱 개만으로 CTF 풀이 보고서(write-up)의 95%를 쓸 수 있습니다. 나머지 5%가 필요해지는 날이 오면 그때 배우면 됩니다.

2-3. 좋은 정리 문서의 구조 — 세 칸

연구 논문이 아니라 미래의 내가 쓸 매뉴얼이므로, 구조는 단순한 쪽이 이깁니다.

# 개념 이름
 ## 한 줄 요약        ← 이게 뭐였더라?
 ## 실습 명령         ← 그래서 뭘 쳤더라?
 ## 막혔던 점         ← 어디서 고생했더라?

"막혔던 점" 칸이 이 위키의 심장입니다. 에러 메시지와 해결법은 검색 가치가 가장 높은 정보입니다 — 같은 에러는 반드시 다시 만나거든요.

3. 따라 하기

3-1. 위키 저장소 개설

입력:

mkdir security-wiki && cd security-wiki && git init

출력 (2026-09-09 실측): Initialized empty Git repository in .../security-wiki/.git/

읽는 법: Step 87의 security-study가 "만든 것"의 전시장이라면, 이 security-wiki는 "아는 것"의 창고입니다. 둘을 분리하는 이유는 검색 범위를 좁히기 위해서입니다. GitHub에 올리고 싶다면 Step 87의 절차 그대로 연결하면 됩니다.

왜 하는가: 위키도 Git으로 관리하면 정리 자체가 커밋으로 쌓여 GitHub 잔디를 채웁니다. 공부 기록과 그 기록의 기록이 한몸이 됩니다.

3-2. 첫 문서 — 개념 한 개 정리

입력: HTTP.md 파일을 만듭니다.

# HTTP

 ## 한 줄 요약
웹의 대화 규약. 요청(클라이언트) → 응답(서버)의 무상태 대화.

 ## 실습 명령
```bash
curl -v http://neverssl.com
```
`-v`로 요청/응답 헤더를 전부 볼 수 있다.

 ## 막혔던 점
- 평문이라 Wireshark에서 내용이 그대로 보였다 (Step 85).
- `tcp.port == 8000`처럼 비표준 포트는 `http` 필터가 못 잡는다.

읽는 법: 세 칸 구조가 그대로입니다. "한 줄 요약"이 성의 없어 보여도 괜찮습니다 — 검색해서 열었을 때 첫 줄에서 기억이 되살아나면 그만입니다.

왜 하는가: 첫 문서는 위키의 표본입니다. 이후 문서 100개가 이 형식을 따라갈 것이니, 형식을 억지로 화려하게 만들지 마세요.

3-3. 트러블슈팅 모음 — 에러 일기장

입력: troubleshooting.md를 만듭니다.

# 트러블슈팅 모음

 ## Git: "Password authentication is not supported"
- 원인: GitHub 비밀번호 인증 폐지
- 해결: PAT 발급 → 비밀번호 자리에 토큰 입력 (Step 87)

 ## nmap: "Host seems down"
- 원인: ping 차단된 호스트
- 해결: `-Pn` 옵션으로 ping 생략 (Step 81)

이 파일에 지금까지 겪은 에러와 해결법을 채워 넣으세요. 입력 후 커밋 (2026-09-09 실측):

3af1be6 문서: HTTP, 트러블슈팅 모음

읽는 법: 에러 메시지는 원문 그대로 적습니다 — 검색은 정확한 문자열로 하니까요. 해결법 옆의 "(Step 87)" 같은 출처 표시는 나중에 맥락이 필요할 때 살 길입니다.

왜 하는가: 고수와 초보의 차이는 "에러를 안 만나는가"가 아니라 "같은 에러에 두 번 막히지 않는가"입니다. 에러를 만나는 순간을 실패가 아니라 "위키에 입고시킬 신상품이 도착한 순간"으로 바꿔 부르는 사람은 빨리 성장합니다.

3-4. 예측해 보기 — 검색이 먹히는 문서는 어떤 문서일까

세 달 뒤 여러분이 "토큰"을 검색합니다. 어떤 문서가 걸릴까요?

(a) "인증에 대하여"라는 제목에 설명만 길게 적은 문서
(b) 에러 원문 "Password authentication is not supported"가 적힌 문서

직접 확인: 방금 만든 위키에서 터미널 검색으로 시험해 봅니다.

grep -rn "authentication" . --include="*.md"
grep -rn "토큰" . --include="*.md"

출력 (2026-09-09 실측):

./troubleshooting.md:3:## Git: "Password authentication is not supported"

./troubleshooting.md:5:- 해결: PAT 발급 → 비밀번호 자리에 토큰 입력

정답은 (b) 입니다. 에러 원문을 적어 둔 문서는 "authentication"과 "토큰" 어느 검색에도 걸립니다. 에디터의 Ctrl+F도 같은 원리입니다.

왜 중요한가: 정리 문서의 품질은 "쓸 때"가 아니라 "찾을 때" 결정됩니다. 규칙은 하나 — 미래의 내가 검색창에 칠 것 같은 단어를 문서 안에 심어 두라.

3-5. 문서 다섯 개 쌓기 — 지금까지의 복습 겸

입력: 지금까지 배운 것 중 다섯 개를 골라 각각 한 파일로 만듭니다. 추천 목록:

포인터.md (Step 49~50의 C 언어)
가상메모리.md (Step 69)
소켓통신.md (Step 77~78)
nmap.md (Step 81)
Wireshark.md (Step 83~84)

읽는 법: 한 문서당 10~15분이면 충분합니다. 책을 다시 펴지 말고 기억나는 대로 쓴 뒤, 틀린 부분만 본편을 보고 고치세요. 기억에서 꺼내는 행위 자체가 복습 효과의 대부분을 만듭니다. 문서마다 "문서: nmap 정리" 같은 커밋을 남기세요.

3-6. 위키의 목차 — README로 색인 만들기

입력: 위키의 README.md:

# security-wiki

보안 공부 개인 위키. 6개월 뒤의 나를 위한 매뉴얼.

 ## 개념 정리
- [HTTP](HTTP.md)
- [포인터](포인터.md)
- [nmap](nmap.md)

 ## 에러 일기장
- [트러블슈팅 모음](troubleshooting.md)

 ## 사용 규칙
매 스텝 종료 후 10분 문서화. 완벽보다 검색 가능성.

읽는 법: 마크다운에서 [이름](파일명)은 GitHub 안에서 클릭 가능한 링크가 됩니다. README가 위키의 대문이자 색인입니다.

왜 하는가: 파일이 50개가 넘어가면 목차 없는 위키는 방치된 서랍이 됩니다. 문서가 생길 때마다 README에 한 줄 추가하는 습관으로 해결합니다. 문서끼리도 링크를 거세요 — nmap.md에 [Wireshark 필터](Wireshark.md)로 스캔 패턴 확인처럼. 지식은 연결된 만큼 오래 남습니다.

3-7. 문서 속 스크린샷 — 이미지 넣기와 폴더 규칙

글만으로 부족한 순간이 옵니다 — "화면이 이렇게 떴다"는 그림 한 장이 설명 열 줄을 이깁니다.

입력:

mkdir images

캡처한 화면을 images/wireshark-filter.png처럼 저장하고, 문서 안에서 이렇게 부릅니다.

![Wireshark 필터 화면](images/wireshark-filter.png)

읽는 법: ![설명](경로) — 느낌표가 붙으면 링크가 아니라 그림입니다. 앞의 설명(대체 텍스트)은 그림이 안 뜰 때 대신 보이는 글이니 빈칸으로 두지 마세요. 경로는 문서가 있는 곳에서의 상대 경로입니다.

주의: 그림 안에 실제 IP·계정이 찍혔다면 반드시 가리고 올리세요. 그림 파일도 Git에 쌓이니, 지운 그림의 과거 커밋 노출 주의(Step 87)는 문서와 똑같이 적용됩니다. 파일명은 날짜-내용.png 형식으로 — 스크린샷(27).png인 위키는 3개월 뒤 아무도 못 찾습니다.

3-8. 지속 가능한 규칙 세우기

위키는 만드는 것보다 유지가 어렵습니다. 유지의 비결은 규칙을 작게 만드는 것입니다.

권장 규칙 (그대로 베껴 써도 됩니다):

매 스텝이 끝나면 10분 문서화 — 미루면 영원히 안 한다
한 문서는 한 화면을 넘기지 않는다 — 길어지면 파일을 나눈다
에러를 만나면 해결 직후 바로 troubleshooting.md에 3줄 추가
매달 첫 주말에 README 색인 정리와 검색 테스트 — 아무 키워드나 골라 30초 안에 찾아지는지 확인

왜 하는가: 기록 습관의 적은 "완벽주의"입니다. 10분짜리 성의 없는 문서 100개가 한 편의 완벽한 문서보다 압도적으로 유용합니다. 그리고 안 지켜지는 규칙이 있으면 자신을 탓하지 말고 규칙을 더 작게 쪼개세요 — "매일 30분"이 무너졌다면 "매 스텝 후 5분"으로.

4. 미션과 연습문제

미션 — 개인 위키 완성

security-wiki 저장소에 세 칸 구조(요약/명령/막혔던 점)의 개념 문서 5개를 씁니다
troubleshooting.md에 에러 원문과 해결 10개를 채웁니다
README 색인에서 모든 문서로 링크를 연결합니다
커밋 5개 이상으로 쌓고, 키워드 2개로 검색 테스트(3-4의 grep 또는 Ctrl+F)를 합니다
"앞으로의 규칙"을 README 맨 아래에 명시합니다

연습문제

문제 1. "제2의 뇌" 원칙에서 머리에 둘 것과 위키에 둘 것의 구분 기준을 설명해 보세요.

문제 2. 에러 메시지를 원문 그대로 적어야 하는 이유를 "검색"이라는 단어와 함께 설명해 보세요.

문제 3. 코드 블록 안에 ```를 포함해 설명하려 할 때 문서가 깨지는 이유와 해결법을 말해 보세요.

문제 4. GitHub에서 문서 간 링크를 눌렀더니 404가 나왔습니다. 가장 흔한 원인과 해결법은 무엇인가요?

5. 모범 답안과 완료 기준

미션 모범 답안

뼈대는 3-2의 HTTP.md가 표본입니다. 문서 5개 × 세 칸 구조, troubleshooting.md는 "에러 제목 / 원인 / 해결 / 출처" 3~4줄씩 10개면 충분합니다. README 색인의 링크는 파일명의 철자·대소문자를 정확히 맞춥니다.

검증하는 법: ① git log --oneline에 커밋 5개 이상이 있는가. ② grep -rn "토큰" . --include="*.md" 같은 검색이 원하는 문서를 찾아내는가. ③ README의 링크 텍스트와 실제 파일명이 일치하는가. ④ README 맨 아래에 규칙이 적혀 있는가. 전부 ‘예’이면 완성입니다.

연습문제 해답

문제 1 해답. 개념과 원리("왜 이렇게 동작하는가")는 머리에, 명령어와 세부 절차("정확히 뭘 쳤는가")는 위키에 둡니다. 뇌는 위치 기억에 강하고 정확한 기억에 약하므로, 정밀한 문자열은 외우는 대신 찾을 수 있게 해 두는 것입니다.

문제 2 해답. 검색은 정확한 문자열로 하기 때문입니다. 에러를 내 말로 바꿔 적으면, 미래의 내가 원문 에러를 검색창에 쳤을 때 걸리지 않습니다 (3-4 실측에서 원문이 적힌 문서만 검색에 걸렸습니다).

문제 3 해답. 마크다운 파서가 안쪽 ```를 먼저 닫힘으로 해석하기 때문입니다. 해결: 바깥쪽을 백틱 4개( ““)로 감쌉니다. 백틱 개수는 안쪽보다 하나만 많으면 됩니다.

문제 4 해답. 가장 흔한 원인은 대소문자 불일치(http.md vs HTTP.md)입니다 — GitHub의 서버는 대소문자를 구분합니다. 파일명과 링크의 철자·대소문자를 정확히 맞추세요. 한글 파일명 링크가 꼬이면 파일명을 영문으로 통일하는 것도 방법입니다.

완료 기준 체크리스트

[ ] 마크다운 일곱 문법을 자유롭게 쓸 수 있다
[ ] 세 칸 구조(요약/명령/막혔던 점)로 개념 문서를 쓸 수 있다
[ ] 에러 원문과 해결법을 트러블슈팅 문서에 기록하는 습관을 시작했다
[ ] README 색인으로 위키 안을 링크로 이동할 수 있다
[ ] "검색 가능성" 기준으로 문서를 점검할 수 있다
[ ] 스크린샷은 images/ 폴더와 대체 텍스트 규칙으로 관리한다
[ ] 미션: 문서 5개와 트러블슈팅 10개를 완성했다

6. 흔한 실수와 해결

벽 1. 코드 블록 안의 코드 블록이 깨진다

증상: 설명하려는 ``` 때문에 문서가 엉망이 됩니다.
원인: 마크다운 파서가 안쪽 표시를 먼저 닫힘으로 해석합니다.
해결: 바깥쪽을 백틱 4개로 감싸세요. 백틱 개수는 안쪽보다 하나만 많으면 됩니다.

벽 2. GitHub에서 링크를 누르면 404가 나온다

증상: 로컬에서는 되는 링크가 GitHub에서 깨집니다.
원인: 대부분 대소문자 불일치(http.md vs HTTP.md). GitHub의 서버는 대소문자를 구분합니다.
해결: 파일명과 링크의 철자·대소문자를 정확히 맞추세요. 한글 파일명 링크가 꼬이면 파일명을 영문으로 통일하는 것도 방법입니다.

벽 3. 정리하다가 하루가 다 간다

증상: 문서 하나에 1시간을 쓰고 있습니다.
원인: "남에게 보여 주는 글"로 쓰고 있습니다. 이 위키의 독자는 미래의 나 한 명입니다.
해결: 타이머를 15분으로 맞추세요. 시간이 되면 미완성이라도 커밋. "나중에 보강" 한 줄이면 충분합니다.

벽 4. 뭘 정리해야 할지 모르겠다

증상: 빈 파일 앞에서 멈춥니다.
원인: "중요한 것"을 고르려 하기 때문입니다.
해결: 질문을 바꾸세요 — "오늘 막혔던 것은?" 막힘은 전부 정리 가치가 있습니다. 막힘이 없는 날은 그날 쓴 명령어 3줄만 적어도 됩니다.

벽 5. 스크린샷에 개인정보가 찍혀 올라갔다

증상: 캡처 화면에 실제 IP·계정·토큰이 보이는 채로 push했습니다.
원인: 그림은 글보다 점검 눈이 느슨해지기 쉽습니다.
해결: 올리기 전 그림을 열어 확대해서 점검하세요. 이미 올라갔다면 — Step 87의 교훈대로 지우는 것으로는 부족합니다. 찍힌 것이 비밀값이라면 폐기·재발급이 정답입니다.

7. 정리

오늘의 개념

개념	한 줄 설명
제2의 뇌	개념은 머리에, 명령어와 절차는 위키에 — 외울 것과 찾을 것의 분리
세 칸 구조	한 줄 요약 / 실습 명령 / 막혔던 점 — 막혔던 점이 검색 가치 1위
검색 가능성	문서 품질의 기준. 미래의 내가 칠 검색어를 심어 둔다
README 색인	위키의 대문이자 목차. 문서가 생기면 한 줄 추가
트러블슈팅 모음	에러 원문 + 원인 + 해결의 일기장. 에러는 입고될 신상품
Write-up	CTF 풀이 보고서 — 오늘의 위키 문서가 나중에 그 재료가 된다

오늘의 문법

문법	쓰는 법
제목	`#`, `##`, `###`
인라인 코드	`명령어`
코드 블록	```언어 … ``` (중첩 시 바깥은 백틱 4개)
목록	`- 항목`
링크	`[이름](파일명-또는-주소)`
이미지	`![대체 텍스트](images/파일.png)`
굵게 / 인용	`<strong>중요</strong>` / `> 원문`

명령어보다 중요한 감각

기록의 진짜 효과는 "나중에 찾는 것"에만 있지 않습니다. 쓰는 행위 자체가 생각을 정리합니다. 개념을 문장으로 옮기다 보면 "알았다고 생각했는데 말이 안 되는 구간"이 드러나고, 그 구멍이 바로 다음에 공부할 것입니다. 또 하나, 위키는 면접의 무기입니다 — "어떻게 공부하셨어요?"라는 질문에 저장소 주소 하나로 답할 수 있는 지원자는 드뭅니다. 100개의 커밋이 쌓인 위키는 "꾸준함"이라는 추상 형용사를 클릭 가능한 증거로 바꿉니다. 오늘의 10분이 그 증거의 한 페이지입니다.

전부 체크되면 Step 89 완료입니다. 사이드바의 체크박스를 눌러 진도를 저장하세요.