DR-0020: 사용법은 둘러보기와 찾아보기의 한 페이지, 그림은 앱에서 찍고 키는 나란히, 영어와 한국어
배경
MVP의 도움말 › 사용법은 /manual/을 새 탭으로 여는데, 그 주소에 아직 아무것도 없다. 사용법은 웹 베타의 문턱이다(DR-0018). 요구사항은 “사용법을 한 페이지로 안내하고, 단축키 목록을 볼 수 있게 한다”(R-EDIT-21, 본보기는 SequenceDiagram.org의 Instructions)뿐이고, 목차와 모양은 정하지 않았다. 고른 과정은 시안 M48에 있다(https://claude.ai/artifact/7rKqHPCcR6UYn8zXbJZCS4, 저장소의 사본 journal/assets/2026-11-02-manual-toc-study.html).
결정 기준
- 처음 온 사람이 5분 안에 하나를 그려 볼 수 있어야 한다.
- 쓰던 사람이 하나를 찾아볼 수 있어야 한다.
- 키보드로 빠르게 그리는 이 앱의 장점(Vim 키)이 숨지 않되, Vim을 모르는 사람도 막히지 않아야 한다.
- 화면과 키가 바뀌어도 사용법이 낡지 않게, 손으로 옮기는 곳을 줄인다.
검토한 대안
M48의 네 물음마다 셋씩: U1 목차(둘러보기 + 찾아보기 · 따라 하기 하나 · 블록과 명령의 사전), U2 한 꼭지의 모양(전 · 후 그림 + 키 · 글과 키만 · 움직이는 그림), U3 키(둘 다 나란히 · 전환 버튼 · 표준 키 먼저), U4 언어(영어와 한국어 · 한국어 먼저 · 영어만). 장단점은 M48에 있다.
결정
메인테이너가 2026-11-02에 골랐다(U1 1번, U2 1번 + 3번, U3 1번, U4 1번).
- 목차: 앞에 “5분 둘러보기”(하나를 처음부터 그려 저장하기까지), 뒤에 일별 “찾아보기”(화면, 블록, 이동과 선택, 넣기 · 글자 고치기, 옮기기 · 복사 · 삭제, 감싸기 · 풀기, 다이어그램, 실행 취소 · 확대, 파일, 커맨드 팔레트, 단축키 전체, 문제 알리기).
- 한 꼭지: 전 · 후 그림 둘과 키. 이해하기 어려운 곳(여러 블록을 고르고 감싸기처럼 손의 움직임이 중요한 곳)에만 움직이는 그림을 더한다.
- 키: 표의 한 줄에 Vim 키와 표준 키 · 마우스를 나란히 둔다. 단축키 목록 모달과 같은 모양이다.
- 언어:
/manual/은 영어,/manual/ko/는 한국어. 도움말 › 사용법은 앱의 화면 언어 쪽을 연다. Claude가 한국어로 쓰고 영어로 옮긴다.
Claude가 정해 둔 것(M48의 “정해 둔 것”, 메인테이너의 확인을 기다림 → 확인해 주세요):
- 한 페이지. 넓은 화면은 왼쪽에 붙은 목차, 좁은 화면은 맨 위의 목차.
- 설계 문서 사이트(Quartz)의 문서가 아니라, 앱과 같은 GitHub Pages 빌드에서 만드는 따로 된 페이지.
- 단축키 전체 표는 빌드할 때 앱의 키 표에서 만든다.
- 그림은 손으로 그리지 않는다. 실제 앱을 조작하며 찍거나(Playwright) 앱의 렌더러로 그려, 화면이 바뀌면 스크립트로 다시 만든다.
결과
- 좋아지는 점: 처음 온 사람과 쓰던 사람이 한 페이지에서 각자의 길을 찾는다. 그림과 키 표가 앱에서 나와 낡지 않는다.
- 감수하는 점: 고칠 때마다 두 언어다. 둘러보기와 찾아보기에 같은 명령이 두 번 나온다(둘러보기는 짧게, 찾아보기로 링크).
- 후속 작업: 웹 베타의 문턱. 첫 초안은 시안 M49(“5분 둘러보기”)다.