Manual authoring

사용자 매뉴얼 작성 (manual-authoring)

첨부된 UI 스크린샷과 사용자가 설명하는 화면 동작을, 인쇄 가능한 A4 사용자 매뉴얼 (HTML → PDF)로 만든다. 매뉴얼은 일관된 시스템을 가진 디자인 문서다 — 러닝 헤더/푸터, 번호 알약, 절차는 번호 배지·정보는 점 불릿, UI 명칭은 키캡, 주의는 콜아웃 박스. 전체가 하나의 자체 완결형 HTML이고, Chrome으로 렌더한 뒤 바뀐 페이지를 반드시 눈으로 확인한다.

작업 초반에 references/layout-notes.md를 읽어라 — 템플릿이 이미 고쳐 둔 레이아웃 함정(고정 높이 flex 잘림, 폰 목업 크기, 병합하지 말고 합치기)을 왜 그렇게 했는지 설명한다. 페이지가 잘리거나 넘칠 때마다 다시 읽어라.

0단계 — 먼저 프로덕트 컨텍스트를 로드한다 (건너뛰지 말 것)

매뉴얼은 그 제품의 실제 용어를 쓰고 정책을 지켜야 한다. 어떤 문구든 쓰기 전에:

1. 어떤 제품의 매뉴얼인지 확인한다(불확실하면 물어본다).
2. references/products.md에서 해당 제품을 찾아 컨텍스트 폴더(정책 git 문서 폴더)를 읽는다. 최신 상태로 먼저 pull한다. pull이 실패하면(인증·네트워크· 충돌) 추정하지 말고 멈추고 보고한다.
3. 그 제품의 용어·객체 모델·톤 규칙을 흡수해 전체에 적용한다(예: 앱은 "탭합니다", 웹 콘솔은 "클릭합니다"; 서로 구분되는 객체를 뭉뚱그리지 않기).
4. 레지스트리에 없는 새 제품이면 먼저 사용자에게 확인한다 — 제품/폴더 이름과 컨텍스트 폴더(정책 문서 위치/리포)를 물어본다. 확인받은 뒤에 (a) 산출물 폴더 ~/manuals/<제품>/를 만들고, (b) references/products.md에 새 행을 추가해 다음 작업부터 이 스킬이 자동으로 그 제품을 인식하게 한다(폴더·행을 임의로 먼저 만들지 말고 반드시 확인부터).

1단계 — 화면 입력을 모은다

내용은 사용자가 스크린샷을 첨부하고 각 화면을 설명하며 이끈다. 페이지마다:

• 넣기 전에 첨부된 스크린샷을 전부 열어 확인한다 — 다시 내보낸 파일은 이름(Group 1.png, IMG_...2.png)이 같아도 내용이 바뀌는 경우가 많으니 절대 파일명을 믿지 말고 실제로 무엇인지 본다.
• (설명에서 추론하거나 물어서) 흐름 순서, UI 요소 이름, 각 화면이 무엇을 보여주는지 파악한다. 여러 장은 페이지 소제목 순서에 맞게 배열한다(진입 → 상세 → 다이얼로그).
• 설명된 동작이 제품 정책(흐름·제한·EMR/EHR 규칙)에 닿으면 0단계 문서와 대조해 제품이 실제로 하는 대로 쓴다.

2단계 — 템플릿으로 페이지를 작성/수정한다

새 매뉴얼은 assets/template.html을 복사하고, 기존 매뉴얼은 프로젝트의 소스 파일을 수정한다. 템플릿에 디자인 시스템과 모든 레이아웃 수정이 들어 있다. 아래 작성 규칙을 따르면 페이지가 일관되게 읽힌다:

• 리드문 — 이 기능으로 무엇을 할 수 있는지 한 문장(~할 수 있습니다).
• 절차 → <ol class="steps"> (번호 배지). 사실·규칙 → <ul class="bul"> (점 불릿). 이 둘을 옳게 고르는 게 시각적 명료함의 대부분이다.
• UI 명칭(버튼·탭) → <span class="kbd">…</span>로 감싼다.
• 주의 / 참고 / 팁 → .note 박스, 페이지 맨 아래.
• 스크린샷: 웹·데스크탑 가로 캡처 → 그냥 <figure>. 폰 캡처 → <figure class="shots rowN"> (N=장수; layout-notes의 높이 표 참고 — 4장 행은 낮춘 높이를 써야 좌우가 안 잘린다).
• 러닝 헤더, .chapter 라벨, .num 알약, .folio 쪽번호를 이웃 페이지와 맞춘다. 섹션 번호(1-1, 2-3…)는 순서를 유지한다 — 페이지를 끼우면 이후 번호와 목차를 다시 매긴다(합본 폴리오는 3단계의 renumber()가 자동 처리).
• 다른 섹션을 가리킬 땐 자세히 · 웹 콘솔 2-2 (18쪽)처럼 파트 접두어 + 섹션 번호 + 쪽번호를 함께 적는다(섹션 번호는 파트마다 겹치므로 접두어로 구분; 쪽번호는 연속 폴리오와 같은 물리 번호).

독자에 맞춘다: 노약자·비전문가 대상이면 본문을 크게(템플릿 기본 13pt) 문장은 짧게.

요청한 만큼만 만든다. "페이지 하나"(또는 기존 매뉴얼에 끼울 페이지)는 <section class="page"> 하나다 — 표지나 목차를 앞에 붙이지 마라. 표지·목차는 완전한 단독 매뉴얼 문서를 원할 때만 넣는다. 기존 매뉴얼에 삽입할 때는 그 매뉴얼의 러닝 헤더 문구·챕터 번호·쪽번호 흐름에 맞춘다.

3단계 — 렌더하고, 눈으로 본다

1. 여러 섹션/에디션이면 하나의 HTML로 합친다 — scripts/build.py에 방식이 있다. PDF를 따로 만들어 병합하지 마라(헤더가 잘린다). 항상 합친 HTML 하나를 렌더한다. 합본이면 build.py의 renumber()로 폴리오·목차 쪽번호를 물리 순서대로 연속 재번호한다(파트별 폴리오를 하드코딩하면 푸터·상호참조가 어긋난다; layout-notes 참고). 에디션 전용 페이지(예: 데모 안내)는 insert_edition_page()로 그 에디션에만 표지 뒤에 끼운다.
2. 렌더: scripts/render.sh <combined.html> <out.pdf>.
3. 눈으로 검증한다 — 이게 핵심 루프이며 선택이 아니다. 바뀐 페이지를 scripts/verify.py <out.pdf> <pages>로 PNG로 뽑아 실제로 읽는다. 페이지마다 확인: 상단 헤더 안 잘림, 하단에서 이미지 안 잘림, 폰 목업 온전(하단 내비·홈 인디케이터까지, 좌우 안 잘림), 텍스트가 푸터를 안 넘음. 잘리면 layout-notes대로 고치고 다시 렌더한 뒤 넘어간다.

verify.py 최초 1회 설치(머신당): python3 -m pip install pyobjc-framework-Quartz

4단계 — 버전과 배포

• 에디션: general 버전 + 고객별 버전(예: 로그인 계정표와 표지에 고객명이 들어간 병원용). 같은 공유 섹션 본문으로 각각을 빌드해 내용 수정이 전 버전에 전파되게 하고, 달라야 하는 페이지만 갈라낸다.
• 파일명: 버전과 대상을 파일명에 넣는다. 예: <제품>-사용자매뉴얼_general-v1.pdf, <제품>-사용자매뉴얼_<고객>-v1.pdf. 다음 개정은 -v2; 새 고객은 새 combined-<에디션>.html + PDF를 추가한다.
• 민감 정보: 실제 계정·비밀번호가 들어간 에디션이면 그 사실을 알리고 내부 전달용으로만 쓴다 — 배포 PDF 속 공용 비밀번호는 유출이다. 넓게 배포할 땐 계정 없는 버전을 따로 제공한다.
• 소스 HTML, img/ 스크린샷, 로고 SVG를 프로젝트에 남겨 두어 나중에 자산을 다시 모으지 않고 재렌더·수정할 수 있게 한다.

파일

• assets/template.html — A4 템플릿 전체: 디자인 시스템 CSS + 표지·표준·폰목업 예시 페이지. 여기서 시작한다.
• scripts/render.sh — 헤드리스 Chrome HTML→PDF.
• scripts/verify.py — 지정한 PDF 페이지를 PNG로 렌더(Quartz). 육안 확인용.
• scripts/build.py — 섹션·에디션을 하나의 HTML로 합치기.
• references/layout-notes.md — 레이아웃이 왜 이렇게 됐는지, 잘림 수정법.
• references/products.md — 제품별 컨텍스트 폴더 + 톤·용어 규칙.