코드보다 README를 먼저 읽는 사용자를 뒤늦게 생각했다
코딩은 AI에게 맡겼습니다 · 시즌 1 / 5
첫 README는 2026년 6월 3일에 추가됐습니다. 한 파일에 104줄이 들어갔습니다. 기능을 만드는 동안에는 코드가 제품의 중심처럼 보이지만, 처음 방문한 사람은 코드를 실행하기 전에 설명을 봅니다.
먼저 보는 핵심
좋은 README는 파일 목록이 아니라 사용자가 설치 여부를 결정하는 화면입니다. 무엇을 해결하는지, 어떻게 설치하는지, 어떤 데이터를 다루는지, 현재 한계가 무엇인지가 첫 화면에서 보여야 합니다.
AI가 만든 문서는 왜 길어지기 쉬운가
AI에게 “README를 작성해줘”라고 요청하면 기능, 설치법, 폴더 구조, 기술 스택, 기여 방법까지 빠르게 만듭니다. 형식은 그럴듯하지만 제품마다 중요한 순서가 다릅니다.
Simple Side Note에서 방문자가 가장 먼저 궁금한 것은 다음 네 가지였습니다.
- 이 확장 프로그램이 무엇을 줄여 주는가
- Chrome 어디에서 열리는가
- 메모가 외부 서버로 전송되는가
- 지금 바로 설치해 시험할 수 있는가
폴더 구조나 사용한 JavaScript 기술은 그다음입니다. README의 첫 화면을 개발자 보고서처럼 만들면 정작 사용 이유가 아래로 밀립니다.
README를 사용자 흐름으로 다시 배열하기
문서의 순서는 다음처럼 잡았습니다.
| 순서 | 답해야 할 질문 |
|---|---|
| 1 | 이 도구는 누구의 어떤 불편을 해결하는가 |
| 2 | 핵심 기능을 한눈에 볼 수 있는가 |
| 3 | 설치 후 첫 사용까지 따라 할 수 있는가 |
| 4 | 데이터와 권한을 믿을 수 있는가 |
| 5 | 제한 사항과 앞으로의 계획은 무엇인가 |
| 6 | 개발자가 구조를 이해할 자료가 있는가 |
AI에게는 “기능 목록을 작성해줘” 대신 “처음 방문한 사용자가 설치를 결정하는 순서로 다시 배열해줘”라고 요청하는 것이 더 나았습니다.
코드에서 사실을 가져오게 했다
문서 초안을 만들 때 가장 위험한 것은 존재하지 않는 기능을 자연스럽게 설명하는 것입니다. AI는 계획 문서와 실제 코드를 혼동할 수 있습니다.
그래서 다음과 같은 근거를 먼저 확인하게 했습니다.
- Manifest에 선언된 실제 권한
- 화면에 존재하는 버튼과 탭
- 저장소에 기록되는 데이터
- 실제 내보내기 형식
- 아직 구현되지 않은 기능 표시
문서에 Coming Soon을 넣는다면 현재 기능과 명확히 분리해야 합니다. 구현 계획이 제품 기능처럼 보이면 사용자는 설치 직후 실망합니다.
README는 출시 전 테스트 목록이기도 하다
설치 절차를 글로 적으면서 누락도 발견할 수 있습니다. 새로운 Chrome 프로필에서 문서만 보고 설치해 보면 개발자 컴퓨터에만 있던 가정을 찾게 됩니다.
- 압축을 풀 위치가 설명되어 있는가
- 개발자 모드를 켜는 단계가 있는가
- 어느 폴더를 선택해야 하는가
- 확장 아이콘을 누른 뒤 무엇이 열리는가
- 권한 경고가 문서 설명과 일치하는가
설명할 수 없는 동작은 대개 제품에서도 정리되지 않은 동작입니다. README는 개발이 끝난 뒤 꾸미는 문서가 아니라 제품의 빈틈을 찾는 도구가 되었습니다.
다음 편
README 다음에는 개인정보처리방침을 만들었습니다. 다음 편에서는 서버가 없는 작은 메모장에도 왜 정책 문서가 필요한지 살펴봅니다.
댓글
댓글 쓰기