개념
건물에는 세 종류의 기록이 남는다. 도면(무엇이 어디에 있나), 공사 일지(언제 무엇을 했나), 그리고 설계 의도 메모(왜 이 기둥을 여기 세웠나). 앞의 둘이 없으면 건물을 관리할 수 없고, 세 번째가 없으면 리모델링할 때 기둥을 잘못 건드린다.
QA의 도구도 정확히 셋이다. 그런데 세 번째가 가장 먼저 포기된다. 결함 등록은 안 하면 당장 티가 나지만, "왜 이렇게 정했는지" 를 안 남기는 것은 몇 달 뒤에야 비용이 돌아오기 때문이다.
세 번째 축 — "왜"를 남기는 도구
레슨 1에서 이슈 추적 도구(Jira)와 테스트 관리 도구(TestRail)의 역할 차이를 배웠다. 문서 협업 도구(Confluence, Notion 등) 는 이 둘과 또 다른 세 번째 질문을 다룬다.
| 도구 | 핵심 질문 |
|---|---|
| 이슈 추적 도구 (모듈 6 레슨 4) | 이 결함이 지금 어떤 상태인가? |
| 테스트 관리 도구 (레슨 1) | 이번 릴리스에서 무엇을 테스트했는가? |
| 문서 협업 도구 | 왜 이렇게 하기로 결정했는가? |
이슈와 테스트 케이스는 "지금 상태"를 보여주지만, 몇 달 뒤 "이거 왜 이렇게 만들었죠?"라는 질문에 답할 근거는 별도로 남겨두지 않으면 사라진다. 문서 협업 도구는 그 근거를 남기는 자리다.
"왜" 가 사라지면 치르는 비용
추상적으로 들리지만 실제로 반복되는 손실이 있다.
| 사라진 것 | 몇 달 뒤 벌어지는 일 |
|---|---|
| 왜 이 범위를 테스트하기로 했나 | 같은 논쟁을 다시 한다 |
| 왜 이 결함을 안 고치기로 했나 | 다시 등록되고 다시 논의된다 |
| 왜 이 케이스를 지웠나 | 누가 다시 만든다 |
| 왜 이 환경 설정이 이렇게 됐나 | 아무도 못 건드린다 |
| 왜 이 예외를 허용했나 | 규칙 위반으로 보여 되돌려진다 |
네 번째 줄이 가장 비싸다. 이유를 모르는 설정은 고치는 것도 두는 것도 위험해서 그대로 방치된다. 레슨 3에서 본 "환경이 서서히 어긋난다" 의 상당 부분이 이 기록 부재 때문이다.
그리고 두 번째 줄은 QA에게 특히 자주 온다. 모듈 6 레슨 1에서 P4로 내려간 결함, 반려된 결함의 사유를 적어 두지 않으면 반년 뒤 똑같은 결함이 올라와 같은 대화를 반복한다.
QA가 Confluence에 남기는 것들
- 테스트 계획서 — 모듈 4(레슨 1)에서 배운 범위·리스크·일정을 문서로 정리해 팀 전체가 볼 수 있게 공유
- 요구사항 리뷰 회의록 — 모듈 2(레슨 6)에서 짚은 모호함과 누락이, 회의에서 어떻게 결론 났는지 기록. "그때 왜 이렇게 정했었지?"를 몇 달 뒤에도 찾을 수 있게 한다
- 테스트 전략·가이드라인 — "우리 팀은 어떤 경우에 회귀 테스트를 전체 실행하는가" 같은, 매번 새로 설명하기 아까운 팀 공통 규칙
- 회고(Retrospective) 기록 — 지난 릴리스에서 무엇이 잘 안 됐고, 다음엔 어떻게 바꾸기로 했는지
문서를 수명으로 분류한다
문서화가 부담이 되는 이유는 모든 문서를 같은 방식으로 관리하려 하기 때문이다. 수명이 다르면 관리 방식도 달라야 한다.
| 수명 | 예 | 관리 방식 |
|---|---|---|
| 거의 안 바뀜 | 테스트 전략, 용어 정의, 환경 구성 원칙 | 공들여 쓰고 분기마다 점검 |
| 느리게 바뀜 | 회귀 범위 기준, 결함 등급 기준 | 바뀔 때 고친다. 소유자를 둔다 |
| 빠르게 바뀜 | 릴리즈별 테스트 범위, 진행 현황 | 손으로 쓰지 않는다(자동 집계) |
| 한 번 쓰고 끝 | 회의록, 결정 기록, 회고 | 고치지 않는다. 날짜가 붙은 기록 |
세 번째 줄이 문서가 낡는 주범이다. 진행 현황이나 결함 건수를 손으로 적어 두면 하루 만에 틀린 숫자가 되고, 그 문서가 틀린 것을 본 사람은 옆 문서도 안 믿는다. 숫자는 도구에서 끌어오거나 링크만 둔다.
네 번째 줄은 반대로 고치면 안 된다. 회의록을 나중에 수정하면 "그때 무엇을 알고 있었나" 가 사라진다. 결정이 바뀌었으면 새 기록을 쓰고 이전 것에 링크를 건다.
남기지 않아도 되는 것
문서화 피로를 막는 가장 확실한 방법은 안 쓸 것을 정하는 것이다.
| 남기지 않는다 | 왜 |
|---|---|
| 도구에 이미 있는 정보 | 결함 목록·실행 결과를 복사하지 않는다 |
| 코드·설정에서 읽을 수 있는 것 | 금방 어긋난다 |
| 한 사람만 쓰는 메모 | 개인 노트로 충분하다 |
| 결정이 아닌 잡담 | 회의록을 길게 만들어 결정이 묻힌다 |
| 스크린샷이 많은 조작 설명 | 화면이 바뀌면 전부 거짓이 된다 |
마지막 줄이 특히 중요하다. 버튼 위치를 그림으로 설명한 문서는 가장 빨리 낡는다. 꼭 필요하면 글로 쓰고("설정 → 알림에서 끈다"), 그림은 흐름을 설명할 때만 쓴다.
가장 값진 문서 — 결정 기록
QA가 남길 문서 중 투입 대비 효과가 가장 큰 것이 결정 기록이다. 형식은 짧을수록 좋다.
제목 결제 모듈 회귀 범위를 전체에서 리스크 상위로 축소
날짜 2026-09-14
결정자 QA 리드, 개발 리드, PM
맥락 2주 주기로 바뀌면서 전체 회귀 4일이 가용 시간의 40%를 차지
결정 고위험 영역 4개만 매 릴리즈, 나머지는 월 1회
근거 최근 6개월 운영 결함 92%가 그 4개 영역에서 발생
위험 저위험 영역의 결함이 늦게 발견될 수 있음 → 운영 지표로 감시
재검토 3개월 후(2026-12) 또는 운영 결함 분포가 바뀔 때"위험" 과 "재검토" 두 줄이 이 문서를 살아 있게 만든다. 결정에는 대가가 있고, 그 대가를 적어 두면 나중에 문제가 생겼을 때 "몰랐다" 가 아니라 "알고 택했다" 가 된다. 모듈 6 레슨 3의 릴리즈 판단과 같은 태도다.
재검토 날짜가 없는 결정은 영구 규칙처럼 굳는다. 상황이 바뀌어도 아무도 되돌릴 생각을 안 한다.
회의록은 결정과 미결만 남긴다
회의록이 길어지면 아무도 안 읽는다. 세 가지만 적으면 충분하다.
| 항목 | 내용 |
|---|---|
| 결정 | 무엇을 하기로 했나 |
| 미결 | 답이 안 난 것 + 누가 언제까지 |
| 참석 | 누가 있었나(나중에 물어볼 사람) |
두 번째가 가장 중요하고 가장 많이 빠진다. 레슨 5의 Three Amigos에서 본 "결정 대기 목록" 이 바로 이것이고, 적어 두지 않으면 누군가 임의로 정한다.
논의 과정을 길게 적지 않는다. 필요한 것은 결론과 그 근거 한 줄이고, 오히려 그 둘이 선명할 때 문서가 읽힌다.
이슈·테스트 케이스와 서로 링크로 연결된다
실무에서는 Confluence 문서 안에 관련 Jira 이슈나 TestRail 스위트로 가는 링크를 걸어둔다. "이 기능의 테스트 전략 문서 → 관련 테스트 스위트 → 실행 결과 → (실패 시) 이슈"까지 클릭 몇 번으로 이어지게 만드는 것이, 레슨 1에서 배운 트레이서빌리티를 문서 차원까지 확장한 것이다.
버전 이력이 만드는 가치
Confluence 같은 도구는 문서가 언제, 누구에 의해, 어떻게 바뀌었는지 이력을 남긴다. "지난달엔 이 조건이 없었는데 언제 추가됐지?"를 이력에서 바로 확인할 수 있다 — 이건 모듈 2(레슨 5)에서 배운 요구사항 변경 추적성과 정확히 같은 원리를, 요구사항 문서 자체에 적용한 것이다.
문서가 오래돼 못 믿게 되는 문제
문서 협업 도구의 가장 흔한 실패는 아무도 안 지켜서 낡아버린 문서다. 화면은 바뀌었는데 스크린샷은 예전 그대로이거나, 결정이 번복됐는데 회의록만 옛날 채로 남아있으면, 사람들은 점점 그 문서를 안 보게 된다. 그러면 처음부터 문서가 없던 것과 다를 게 없다.
이 문제에는 구조적인 해법이 있다. 숫자와 목록을 손으로 적지 않고 매크로로 심어두면 문서가 스스로 갱신된다. 그 구체적인 방법 — Jira 연동 매크로, 여러 페이지의 결과를 자동 집계하는 콘텐츠 속성 보고서, 그리고 draw.io로 그리는 QA 다이어그램 — 은 모듈 22 (레슨 9~10) 에서 실습으로 이어 받는다.
문서를 살아 있게 유지하는 네 장치
매크로 외에도 운영 규칙으로 막을 수 있는 것이 있다.
| 장치 | 어떻게 |
|---|---|
| 소유자 | 문서 맨 위에 담당자 이름. 없으면 아무도 안 고친다 |
| 최종 점검일 | "마지막 확인: 2026-09-14" 를 적는다 |
| 유효기간 | "2026-12 재검토" — 지나면 경고로 보인다 |
| 자동 집계 | 숫자·목록은 손으로 적지 않는다(모듈 22) |
세 번째가 가장 효과적이면서 가장 안 쓰인다. 문서에 "언제까지 유효" 가 적혀 있으면 읽는 사람이 스스로 신뢰도를 판단할 수 있다. 날짜가 지났어도 "지난 문서구나" 를 알고 읽는 것과, 최신인 줄 믿고 읽는 것은 완전히 다르다.
첫 번째도 간단하지만 효과가 크다. 소유자가 없는 문서는 모두의 것이고 따라서 아무의 것도 아니다.
문서를 지우는 용기
낡은 문서를 지우지 않는 것이 문서 체계를 망가뜨린다. 검색하면 옛 문서가 먼저 나오고, 그것을 읽은 사람이 틀린 일을 한다.
판단 기준을 정해 두면 쉽다.
- 1년간 아무도 안 열었고 소유자도 모른다 → 지운다
- 내용이 틀렸지만 "그때는 그랬다" 는 기록으로 값이 있다 → 보관 영역으로
옮기고 제목에
[보관]을 붙인다 - 새 문서로 대체됐다 → 지우고 새 문서 링크만 남긴다
두 번째가 결정 기록·회의록의 처리 방식이다. 지우지 않지만 현재 문서와 섞이지 않게 한다. 그래야 "왜 그렇게 했나" 는 남고 "지금 어떻게 하나" 는 선명해진다.
검색되게 쓰기
문서가 쌓이면 구조보다 검색이 중요해진다. 목차를 잘 짜도 사람들은 검색창을 쓴다.
| 나쁜 제목 | 좋은 제목 |
|---|---|
| 테스트 계획 | [2026-Q4] 결제 개편 테스트 계획 |
| 회의록 | [회의록 2026-09-14] 쿠폰 정책 리뷰 |
| 가이드 | [가이드] 회귀 테스트 범위 정하는 기준 |
| 환경 | [환경] 스테이징 접속·계정·초기화 절차 |
앞에 꺾쇠로 분류를 붙이는 것만으로 검색 결과가 읽히기 시작한다. 그리고 날짜가 붙으면 최신인지 한눈에 보인다.
본문에도 사람들이 검색할 단어를 넣어 둔다. "회귀 범위" 라고만 쓰면 "리그레션" 으로 검색하는 사람이 못 찾는다. 첫 문단에 두 표현을 모두 쓰는 작은 습관이 도움이 된다.
신입이 첫 주에 읽을 한 장
문서가 많아도 어디서 시작할지 모르면 쓸모가 없다. QA 공간의 첫 페이지를 안내문 한 장으로 두면 온보딩 비용이 크게 줄어든다.
■ 우리 팀 QA 시작하기
1. 제품이 무엇인지 → [제품 개요] 링크
2. 어디서 테스트하나 → [환경] 접속·계정 절차
3. 무엇을 보나 → [가이드] 회귀 범위 기준
4. 케이스는 어디 → TestRail 프로젝트 링크
5. 결함은 어디 → Jira 프로젝트 + 등록 템플릿
6. 막히면 누구에게 → 담당 영역별 연락처
7. 왜 이렇게 하나 → [결정 기록] 목록7번이 이 레슨의 요지다. 1~6번은 다른 도구에도 있지만, 7번은 여기밖에 없다. 신입이 "왜 이렇게 하죠" 를 물을 때마다 선임이 설명하는 대신, 그 목록을 읽게 하면 같은 설명을 반복하지 않는다.
사례 — 같은 논쟁을 세 번 한 팀
"결제 모듈은 매 릴리즈 전체 회귀를 돌린다" 는 규칙이 있었다. 아무도 이유를 몰랐고, 2주 주기로 바뀌면서 그 4일이 가용 시간의 40% 를 먹었다.
| 시점 | 무엇이 있었나 |
|---|---|
| 1차 논의(3월) | "줄이자" → "위험하다" → 결론 없이 끝 |
| 2차 논의(6월) | 같은 대화 반복. 3월에 무슨 이야기를 했는지 아무도 모름 |
| 3차 논의(9월) | 또 같은 대화 |
9월에 QA가 결정 기록 한 장을 썼다. 쓰면서 한 일은 두 가지였다 — 최근 6개월 운영 결함을 영역별로 집계하고(모듈 6 레슨 5), 그 숫자를 문서에 넣은 것이다.
결정 고위험 4개 영역만 매 릴리즈, 나머지는 월 1회 근거 운영 결함 92%가 그 4개 영역에서 발생 위험 저위험 영역 결함이 늦게 발견될 수 있음 → 운영 지표로 감시 재검토 3개월 후 또는 결함 분포가 바뀔 때
그 뒤 같은 논쟁이 다시 일어나지 않았다. 흥미로운 점은 결론 자체가 3월에 나왔을 수도 있는 결론이라는 것이다 — 달라진 것은 그것을 적었다는 사실뿐이다.
그리고 12월 재검토에서 숫자를 다시 뽑았더니 분포가 바뀌어 영역 하나가 추가됐다. 재검토 날짜가 없었다면 그 규칙은 영구히 굳었을 것이다.
실무에서 왜 필요한가
신입 QA가 팀에 합류했을 때 "우리 팀은 왜 이 방식으로 테스트하나요?" 라는 질문에 선임이 매번 구두로 설명해야 한다면, 그 선임의 시간이 계속 소모된다. 잘 정리된 Confluence 문서가 있으면 새로 온 사람이 스스로 찾아 읽고, 정말 애매한 부분만 질문하면 된다. 또한 "그때 왜 이렇게 결정했는지"에 대한 근거가 문서로 남아있지 않으면, 같은 논쟁을 몇 달마다 반복하게 된다 — 이건 조직 전체의 시간 낭비다.
문서는 QA의 일을 보이게 만든다
QA의 작업은 아무 일도 없었을 때 가장 안 보인다(모듈 6 레슨 5). 문서는 그 공백을 메우는 또 하나의 수단이다. 테스트 전략·범위 기준·결정 기록이 남아 있으면, 그것을 만든 사람이 한 판단이 기록으로 존재한다.
특히 결정 기록이 그렇다. "회귀 범위를 줄였고 근거는 이것이며 위험은 이렇게 감시한다" 는 한 장은 케이스 100개를 실행한 것보다 조직에 미친 영향이 크다.
한 번 쓰면 반복 설명이 사라진다
같은 질문에 세 번 이상 답했으면 문서로 옮길 신호다. 흔한 것들이 있다.
- 어느 환경에 어떻게 접속하나(레슨 3)
- 테스트 계정은 무엇을 쓰나(레슨 2)
- 회귀를 전체 돌리는 기준이 무엇인가(모듈 8)
- 결함 등급을 어떻게 매기나(모듈 6 레슨 1)
- 릴리즈 판단은 누가 어떻게 하나(모듈 4 레슨 5)
다섯 개를 다 적어 두면 선임의 하루가 달라진다. 그리고 신입이 스스로 읽고 "정말 애매한 것만" 질문하게 되므로, 대화의 질도 올라간다.
문서가 없으면 결정이 사람에게 묶인다
가장 실질적인 위험이 이것이다. "왜 이렇게 하나" 를 한 사람만 아는 상태는 그 사람이 쉬거나 떠날 때 팀의 판단력이 사라지는 상태와 같다. 레슨 9에서 다루는 버스 팩터 문제가 문서 쪽에서 나타나는 모습이다.
채용시장에서의 위치
공고에 "Confluence 사용 경험" 이 적히지만, 면접에서 도구 조작을 묻는 경우는 거의 없다. 묻는 것은 무엇을 남겼고 그것이 어떻게 쓰였나다.
| 질문 | 약한 답 | 강한 답 |
|---|---|---|
| "Confluence 써보셨어요?" | "테스트 계획서 작성했습니다" | "결정 기록을 남겼습니다. 위험과 재검토 날짜까지 적어서 같은 논쟁이 반복되지 않았습니다" |
| "문서가 낡는 문제는요?" | "주기적으로 업데이트합니다" | "소유자·최종 점검일·유효기간을 적고, 숫자는 손으로 안 적습니다" |
| "문서를 얼마나 쓰세요?" | "최대한 많이 남깁니다" | "수명으로 나눕니다. 빠르게 바뀌는 건 손으로 안 쓰고, 도구에 있는 건 복사하지 않습니다" |
| "온보딩 문서를 만들어 보셨어요?" | "정리해 뒀습니다" | "첫 주에 읽을 한 장을 만들고 나머지는 링크로 뒀습니다" |
| "안 쓰는 문서는 어떻게 하세요?" | "그냥 둡니다" | "지웁니다. 검색에서 먼저 나와 사람들이 틀린 일을 합니다" |
세 번째가 가장 변별력이 크다. "많이 남긴다" 는 답은 문서화를 해 본 적 없는 사람의 답이다. 실제로 운영해 본 사람은 안 쓸 것을 정하는 것이 더 어렵다는 것을 안다.
다섯 번째도 좋다. 지우는 판단을 할 수 있는 사람은 문서를 자산이 아니라 유지 비용이 드는 것으로 보는 사람이다.
공고 표현으로는 "QA 문서화", "테스트 산출물 관리", "지식 관리", "프로세스 문서화" 가 이 레슨에 걸린다. 그리고 규제 산업에서는 문서 자체가 제출 산출물이므로 이 역량의 비중이 훨씬 커진다(레슨 6).