통합 기능 매뉴얼 장문 샘플

통합 기능 매뉴얼 장문 샘플

이 문서는 Glif의 문서 작성, 편집, 탐색, 렌더링, 배포 흐름을 한곳에 모아 장문 편집을 테스트하기 위한 샘플이다. 실제 공개 매뉴얼로 확정된 문서가 아니라, 나중에 기능별 문서로 분리하기 전까지 긴 문서 성능과 구조를 함께 점검하는 통합 초안이다.

샘플의 목적은 세 가지다. 첫째, 50k 이상의 Markdown 문서를 열고 스크롤하고 편집할 때 에디터가 안정적으로 반응하는지 확인한다. 둘째, heading outline, 링크, 표, 코드 블록, 인용, 체크리스트, fenced block이 긴 문서 안에서 함께 쓰일 때도 읽기 흐름이 유지되는지 확인한다. 셋째, 이 문서를 나중에 시작하기, 문서 작성, 표 편집, 지식 그래프, PDF 출력, 배포 같은 독립 문서로 나눌 수 있도록 장의 경계를 미리 만든다.

이 문서는 테스트용 통합 매뉴얼이다. 부분적으로 계획이나 점검 기준을 설명하지만, 구현되지 않은 기능을 shipped 기능처럼 약속하지 않는다.

분리 계획

장문 테스트 체크리스트

• 문서를 열었을 때 첫 화면이 과하게 늦게 표시되지 않는다.
• outline에서 1단계부터 4단계 heading까지 탐색할 수 있다.
• 표와 코드 블록 근처에서 커서를 옮겨도 입력 리듬이 크게 깨지지 않는다.
• 문서 중간에서 텍스트를 추가하고 저장 상태를 확인할 수 있다.
• 내부 링크를 따라가도 현재 문서의 스크롤과 선택 상태가 예측 가능하다.
• 검색, 그래프, publish 변환이 긴 본문 때문에 실패하지 않는다.

1장. Glif에서 문서를 다루는 기본 생각

Glif의 문서는 Markdown 파일을 중심으로 움직인다. 본문은 사람이 읽고 고칠 수 있는 .md 텍스트로 남고, 표 너비나 병합 상태처럼 Markdown 문법만으로 표현하기 어려운 일부 표현 정보는 문서별 표시 설정으로 관리한다. 이렇게 하면 문서를 다른 도구에서 열어도 본문은 사라지지 않고, Glif 안에서는 좀 더 편한 편집 경험을 제공할 수 있다.

Markdown 원문을 source of truth로 둔다는 말은 모든 UI가 원문을 숨기기만 한다는 뜻이 아니다. 사용자는 표를 직접 셀처럼 다루고, 링크를 클릭해 이동하고, 코드 블록이나 다이어그램을 미리 볼 수 있다. 다만 이런 표현은 원문을 대체하는 새 문서 형식이 아니라, 원문을 더 잘 쓰기 위한 투영으로 이해하는 것이 좋다.

장기적으로 안정적인 문서 시스템을 만들려면 기능보다 흐름을 먼저 이해해야 한다. 문서를 만들고, 쓰고, 연결하고, 저장하고, 다시 열고, 배포하는 경로가 안정적이어야 한다. 화려한 렌더링보다 중요한 것은 사용자가 지금 쓴 문장이 안전하게 남아 있고, 나중에 찾을 수 있으며, 다른 사람에게 전달할 수 있다는 확신이다.

1.1 문서와 바인더

바인더는 문서 묶음이다. 바인더 안에는 Markdown 문서, 섹션 인덱스, 리소스, 배포에 필요한 설정이 들어갈 수 있다. 작은 개인 메모에서는 폴더 하나가 곧 바인더처럼 느껴질 수 있고, 팀 문서에서는 제품, 운영, 회의, 설계 같은 영역을 나눠 관리할 수 있다.

바인더를 잘 운영하려면 이름을 안정적으로 붙이는 것이 중요하다. 문서 이름은 검색어가 되고, 그래프의 노드가 되고, 배포 URL의 일부가 된다. 임시 이름으로 시작해도 괜찮지만, 문서가 기준 문서가 되면 제목과 파일명을 다시 정리하는 편이 좋다.

1.2 문서의 생명주기

문서는 보통 초안 -> 검토 -> 기준 -> 구현됨 -> 오래됨의 흐름을 가진다. 모든 문서에 상태 표시가 필요한 것은 아니지만, 오래 유지해야 하는 문서라면 현재 상태를 본문 앞쪽에 남기는 것이 좋다. 특히 사용자에게 보이는 매뉴얼은 구현과 검증이 끝난 사실만 설명해야 한다.

1.3 장문 문서의 작성 리듬

장문 문서는 한 번에 완성하려고 하면 관리가 어려워진다. 먼저 큰 heading을 만들고, 각 heading 아래에 한 문단짜리 목적을 적는다. 그 다음 표, 체크리스트, 코드 블록처럼 구조화된 요소를 넣는다. 마지막에 문단 사이의 연결을 다듬는다.

긴 문서에서는 같은 말을 반복하기 쉽다. 반복이 독자를 돕는 경우도 있지만, 같은 사실이 여러 장에 흩어지면 나중에 갱신이 어렵다. 반복되는 설명은 한 곳에 두고 다른 장에서는 링크로 연결한다. 이 문서도 나중에 분리할 것을 고려해 각 장의 첫 문단에 독립 문서가 되었을 때의 목적을 적어 둔다.

2장. 첫 문서 만들기

첫 문서는 완벽한 구조보다 빠른 저장 경험이 중요하다. 사용자는 새 문서를 만들고, 몇 줄을 쓰고, 저장되었는지 확인하고, 다시 열 수 있어야 한다. 이 기본 흐름이 흔들리면 표, 그래프, PDF 같은 고급 기능은 신뢰를 얻기 어렵다.

2.1 새 문서의 제목

제목은 문서의 첫 번째 검색 인터페이스다. 제목이 불명확하면 그래프에서도, 파일 목록에서도, 배포 문서에서도 의미가 흐려진다. 좋은 제목은 짧고 구체적이다. 예를 들어 회의록보다 2026-06-06 문서 배포 점검 회의록이 나중에 찾기 쉽다.

새 문서를 만들 때는 임시 제목으로 시작해도 된다. 다만 문서가 공유되거나 링크되기 전에 제목을 다시 확인한다. 문서 제목과 파일명이 다르면 혼란이 생길 수 있으므로, 가능하면 둘의 의미를 맞춘다.

2.2 첫 문단

첫 문단에는 문서의 목적을 적는다. 긴 배경 설명보다 “이 문서는 무엇을 결정하거나 설명하는가”를 먼저 둔다. 독자는 첫 문단만 보고 계속 읽을지 판단한다. 작성자도 첫 문단을 기준으로 본문이 옆길로 새는지 확인할 수 있다.

다음 템플릿은 대부분의 문서에 쓸 수 있다.

# 문서 제목

이 문서는 무엇을 설명하거나 결정하기 위한 문서다.
현재 기준, 대상 독자, 완료 조건을 짧게 적는다.

2.3 저장 상태 확인

문서를 작성할 때 저장 상태는 눈에 띄되 방해가 되면 안 된다. 사용자는 저장 중인지, 저장되었는지, 문제가 있는지 알 수 있어야 한다. 저장 실패나 외부 변경 충돌이 생기면 조용히 숨기지 말고 사용자가 다음 행동을 선택할 수 있도록 해야 한다.

장문 테스트에서는 문서 중간과 끝에서 각각 문장을 추가하고 저장 상태를 확인한다. 긴 문서에서 저장이 느려지면 사용자는 커서가 멈춘 것인지, 저장이 진행 중인지 구분하기 어렵다. 따라서 저장 표시는 단순한 UI 장식이 아니라 신뢰 루프의 일부다.

2.4 다시 열기

문서를 다시 열었을 때 마지막 작성 위치, 선택 상태, 스크롤 위치가 최대한 예측 가능해야 한다. 항상 완벽히 복원할 필요는 없지만, 사용자가 문서를 잃었다고 느끼면 안 된다. 특히 긴 문서에서는 맨 위로 돌아가는 일이 반복되면 작성 흐름이 크게 끊긴다.

3장. 에디터 기본기

에디터는 글을 쓰는 표면이다. 좋은 에디터는 많은 버튼을 보여주는 도구가 아니라, 사용자가 문장을 이어 쓰는 동안 방해하지 않는 공간이어야 한다. 필요한 명령은 가까운 곳에 있어야 하지만, 항상 눈에 띄어서는 안 된다.

3.1 조용한 작성 표면

조용한 작성 표면은 빈 화면이 아니다. 현재 줄, 선택 범위, 문단 폭, 저장 상태, 문서 경로처럼 필요한 정보는 남아 있어야 한다. 다만 그 정보가 본문보다 더 큰 소리를 내면 안 된다. 글을 쓰는 동안 hover 효과, animation, toolbar, 상태 메시지가 계속 움직이면 사용자는 문장보다 UI를 의식하게 된다.

장문 문서에서는 조용함이 더 중요해진다. 화면에 보이는 것은 문서의 일부일 뿐이고, 사용자는 전체 구조를 outline과 검색에 맡긴다. 본문 표면이 카드처럼 여러 겹으로 감싸지거나, 주변 패널이 과하게 강조되면 긴 글의 흐름이 쉽게 끊긴다.

3.2 읽기 폭

본문 폭은 너무 넓어도, 너무 좁아도 읽기 어렵다. 읽기 폭은 문단의 리듬을 만든다. 짧은 메모는 넓은 화면에서도 괜찮지만, 긴 설명은 중앙의 안정적인 폭 안에 있을 때 훨씬 덜 피곤하다.

표나 코드 블록은 본문 폭보다 넓어질 수 있다. 이때 본문 전체 폭을 무리하게 넓히기보다, 해당 블록이 필요한 만큼 가로 스크롤이나 독립적인 표시 방식을 쓰는 편이 낫다. 일반 문단의 읽기 리듬은 유지되어야 한다.

3.3 현재 줄과 문단

현재 줄 표시는 사용자가 커서를 잃지 않게 도와준다. 그러나 강조가 너무 강하면 selection이나 검색 결과와 충돌한다. 현재 문단 표시는 더 조심해야 한다. 문단 전체를 크게 칠하면 긴 글에서 시각적 피로가 생길 수 있다.

현재 줄과 문단 표시는 IME 조합, multi-selection, 표 셀 편집과 충돌하지 않아야 한다. 한국어 입력 중에는 조합 문자열이 안정적으로 보이는 것이 우선이다. 커서 주변의 장식이 조합 중인 글자를 가리면 안 된다.

3.4 선택과 명령

선택한 텍스트에 명령을 적용할 때는 사용자가 예상한 범위만 바뀌어야 한다. 특히 Markdown 문법을 숨기거나 렌더링하는 에디터에서는 보이는 텍스트와 실제 원문 범위가 다를 수 있다. 명령은 원문 범위를 기준으로 안전하게 적용되어야 한다.

다중 선택은 강력하지만 복잡하다. 명령이 다중 선택을 지원하지 않으면 조용히 실패하지 말고 비활성 상태로 남거나 안전한 안내를 제공해야 한다. 장문 테스트에서는 여러 위치에 커서를 두고 굵게, 목록, 코드 같은 명령을 적용해 보는 것이 좋다.

4장. Markdown 작성

Markdown은 가볍고 오래가는 문서 형식이다. Glif는 Markdown을 버리지 않고, 더 편하게 쓰기 위한 편집 표면을 제공한다. 원문을 보존하는 것이 중요한 이유는 도구가 바뀌어도 문서가 남아야 하기 때문이다.

4.1 heading

Heading은 문서의 뼈대다. 긴 문서에서는 heading이 곧 navigation이다. 하나의 장에는 하나의 주제를 두고, 하위 heading은 질문이나 작업 단위로 나눈다. heading이 너무 많으면 outline이 복잡해지고, 너무 적으면 긴 문서에서 위치를 찾기 어렵다.

# 문서 제목

## 큰 장

### 세부 주제

#### 검증 포인트

이 문서는 장문 테스트를 위해 heading을 많이 포함한다. outline 성능과 active heading 표시를 확인할 때 각 장을 빠르게 이동해 본다.

4.2 목록

목록은 정보를 빠르게 훑게 해준다. 그러나 목록만 이어지면 맥락이 약해진다. 긴 문서에서는 목록 앞에 짧은 설명 문단을 두고, 목록 뒤에 결정이나 다음 행동을 적는다.

• 좋은 목록은 서로 같은 층위의 항목을 담는다.
• 목록 안에 너무 긴 문장을 넣으면 표나 별도 문단이 낫다.
• 체크리스트는 완료 여부가 중요한 작업에만 쓴다.
• 순서가 중요한 경우에는 번호 목록을 사용한다.

4.3 인용

인용은 원문, 원칙, 요약을 구분할 때 유용하다. 인용을 강조 박스처럼 남용하면 본문 리듬이 깨진다. 운영 문서에서는 중요한 원칙 하나를 인용으로 남기고, 나머지는 일반 문단으로 설명하는 편이 좋다.

문서가 길수록 각 장의 첫 문단과 마지막 문단이 중요하다. 첫 문단은 목적을 주고, 마지막 문단은 다음 행동을 준다.

4.4 코드와 설정

코드 블록은 정확히 복사해야 하는 내용을 담는다. 파일 경로, 설정, API 예시는 코드 블록으로 분리하는 것이 좋다. 코드 블록 안에서는 일반 Markdown 렌더링이 적용되지 않아야 한다.

{
  "document": "full-manual-long-sample",
  "purpose": "long-form editor and publish smoke",
  "checks": ["outline", "links", "tables", "code-fences", "scroll"]
}

4.5 링크

링크는 문서 사이의 관계를 만든다. 링크는 너무 많이 걸면 읽기 흐름을 방해하지만, 중요한 기준 문서와 후속 문서에는 반드시 연결해야 한다. 이 샘플은 작성 워크플로 샘플, 렌더러 점검 샘플, 지식 운영 샘플과 함께 쓸 수 있다.

5장. Slash Command와 Block Inserter

명령은 글쓰기 흐름 안에서 자연스럽게 호출되어야 한다. 명령을 찾기 위해 손을 오래 멈추면 글쓰기의 리듬이 깨진다. Slash Command와 Block Inserter는 자주 쓰는 Markdown 블록을 빠르게 삽입하기 위한 표면이다.

5.1 Slash Command

Slash Command는 줄 앞쪽에서 /를 입력해 명령 후보를 여는 방식이다. 이 방식은 keyboard-first 흐름에 잘 맞는다. 사용자는 마우스를 쓰지 않고도 heading, 목록, 인용, 코드 블록 같은 기본 구조를 만들 수 있다.

명령은 fenced code나 inline code 안에서 열리지 않아야 한다. 코드 안의 /는 명령이 아니라 코드 문자다. IME 조합 중에도 명령이 끼어들면 안 된다. 한국어 입력 중 명령 popup이 열리면 사용자는 조합 중인 글자가 깨졌다고 느낄 수 있다.

5.2 Block Inserter

Block Inserter는 현재 블록 근처에서 명령을 열 수 있게 하는 작은 affordance다. 문서에 임시 / 문자를 넣지 않고 같은 command registry를 사용해야 한다. 이렇게 하면 slash command와 block inserter가 서로 다른 명령 목록을 갖는 문제를 피할 수 있다.

Block Inserter는 항상 보여서는 안 된다. 글을 쓰는 동안 본문 옆에 큰 버튼이 계속 떠 있으면 조용한 작성 표면을 해친다. 현재 블록, focus, hover 같은 문맥에서만 작게 드러나는 편이 좋다.

5.3 명령 카탈로그

명령 카탈로그는 작은 것부터 시작한다. heading, bullet list, numbered list, quote, code block, table 같은 기본 Markdown 블록이 먼저다. 이후 callout, image, embed, diagram 같은 확장 명령을 추가할 수 있다.

6장. Markdown 표 편집

표는 Markdown 안에서 가장 복잡한 편집 대상 중 하나다. 원문은 pipe table이지만, 사용자는 셀 단위로 이동하고 선택하고 정렬하고 병합하고 싶어 한다. Glif의 표 편집은 Markdown 원문을 보존하면서 셀 편집 경험을 제공하는 방향을 가진다.

6.1 표의 기본 구조

Markdown 표는 header, separator, body로 구성된다. separator는 열 정렬 정보를 담을 수 있다. 간단한 표는 원문으로도 쉽게 읽히지만, 열이 많거나 셀이 길어지면 직접 원문을 고치기 어렵다.

6.2 셀 이동

셀 이동은 빠르고 예측 가능해야 한다. Tab, Shift+Tab, Enter, 방향키는 사용자가 이미 기대하는 방식으로 동작해야 한다. 셀 안에서 줄바꿈이 필요한 경우와 다음 셀로 이동하는 경우를 구분하는 정책도 필요하다.

장문 테스트에서는 표 근처에서 일반 본문을 입력하고, 표 안으로 이동하고, 다시 본문으로 빠져나오는 흐름을 확인한다. 표 편집이 문서 전체 입력 리듬을 막아서는 안 된다.

6.3 셀 선택과 병합

직사각형 범위 선택은 병합과 차트 참조의 기본이다. 마우스 드래그나 Shift+방향키로 범위를 선택할 수 있고, Ctrl 또는 Cmd 클릭으로 개별 셀 선택을 토글할 수 있다. 다만 비연속 선택은 병합 대상으로 적합하지 않다.

셀 병합은 Markdown 표 문법만으로는 표현하기 어렵다. 따라서 원문에 rowspan이나 colspan을 억지로 넣지 않고, 표시 설정으로 보존하는 편이 안전하다. Glif 밖에서 열면 기본 표 원문은 그대로 남고, Glif 안에서는 병합 표시가 복원된다.

6.4 표와 차트

표의 전체 또는 선택 범위는 차트의 데이터 출처가 될 수 있다. 이때 차트가 데이터를 복사하지 않고 원본 표의 범위를 참조하면, 문서의 source of truth가 분리되지 않는다. 원본 표가 바뀌면 차트도 같은 출처를 다시 읽을 수 있다.

차트 참조는 숫자 열을 필요로 한다. 범위 안에 숫자 데이터가 없으면 차트를 만들지 않는 것이 낫다. 잘못된 차트를 자동으로 만드는 것보다, 사용자가 범위를 다시 선택하도록 안내하는 편이 안전하다.

7장. 링크, 참조, 임베드

문서가 많아질수록 링크는 단순한 이동 수단을 넘어 지식 구조가 된다. 링크는 문서 사이의 관계를 보여주고, 그래프를 만들고, 나중에 어떤 결정이 어떤 근거와 연결되었는지 찾게 해준다.

7.1 일반 링크

일반 Markdown 링크는 가장 오래가는 연결 방식이다.

[문서 제목](relative/path/to-document/)

가능하면 상대 링크를 사용한다. 같은 바인더 안에서 문서를 이동하거나 배포할 때 상대 링크가 더 안정적이다. 링크 텍스트는 여기보다 목적을 설명하는 말이 좋다.

7.2 Wiki 스타일 링크

Wiki 스타일 링크는 빠른 작성에 유용하다. [[문서 제목]]처럼 짧게 입력할 수 있고, 같은 바인더 안의 문서를 빠르게 참조할 수 있다. 다만 배포나 외부 도구와의 호환성은 일반 Markdown 링크보다 더 많은 변환 정책을 요구할 수 있다.

Wiki 링크를 쓸 때는 문서 제목이 안정적이어야 한다. 같은 제목의 문서가 여러 개 있으면 링크 해석이 모호해진다. 큰 바인더에서는 경로나 별칭 정책이 필요할 수 있다.

7.3 링크 미리보기

링크 미리보기는 이동 전에 대상 문서의 일부를 보여준다. 이 기능은 빠른 탐색에 좋지만, 입력 중인 문서의 성능을 해치면 안 된다. hover나 pointer path에서 전체 문서를 매번 materialize하거나, 큰 syntax tree를 강제로 만들면 긴 문서에서 지연이 생길 수 있다.

장문 테스트에서는 링크가 많은 문서에서 hover, click, keyboard navigation을 각각 확인한다. 미리보기가 늦게 도착했을 때 현재 문서와 링크 위치가 바뀌었다면 stale 결과를 버려야 한다.

7.4 임베드

임베드는 다른 문서나 블록의 내용을 현재 문서 안에 보여주는 방식이다. 임베드는 편리하지만 source of truth를 흐릴 수 있다. 따라서 임베드가 실제 원문을 복사하는지, 참조만 하는지, 실패했을 때 어떻게 보이는지 명확해야 한다.

임베드 실패는 본문 입력을 막아서는 안 된다. 대상 문서를 찾을 수 없거나 렌더링이 실패하면 조용한 실패 상태와 원문 reveal 경로를 제공하는 것이 좋다. 사용자는 원문을 고쳐 문제를 해결할 수 있어야 한다.

8장. 지식 그래프

지식 그래프는 문서 사이의 링크 관계를 시각적으로 보여준다. 그래프는 문서가 많아질수록 유용하지만, 모든 문서를 항상 같은 비중으로 보여주면 오히려 복잡해진다. 그래프는 탐색의 보조 도구이지, 문서 구조를 대체하는 도구가 아니다.

8.1 그래프를 볼 때의 질문

그래프를 열 때는 먼저 질문을 정한다. 어떤 문서가 고립되어 있는지 보고 싶은가, 특정 주제 주변의 문서를 보고 싶은가, 배포 섹션 구조를 확인하고 싶은가에 따라 필요한 표시 방식이 달라진다.

• 고립 문서 찾기: 링크가 없는 문서를 확인한다.
• 중심 문서 찾기: 많은 문서가 참조하는 기준 문서를 찾는다.
• 구조 확인: _index.md 같은 섹션 문서를 포함할지 결정한다.
• 작업 범위 확인: 최근 변경된 문서 주변의 연결을 본다.

8.2 _index.md 처리

Hugo 같은 섹션 기반 배포 구조에서는 _index.md가 섹션 페이지 역할을 한다. 작성 화면의 그래프에서는 _index.md가 너무 많이 보이면 실제 작성 문서보다 구조 문서가 더 두드러질 수 있다. 그래서 기본 그래프에서는 숨기고, 배포 구조를 확인할 때만 포함하는 방식이 유용하다.

배포 그래프나 사이트 구조 점검에서는 _index.md가 중요하다. 섹션 제목, 순서, 메뉴 구조가 여기에 들어갈 수 있기 때문이다. 그래프 설정에서 인덱스 파일 포함 여부를 바꿀 수 있으면 두 목적을 모두 만족할 수 있다.

8.3 그래프와 문서 품질

그래프가 복잡하다고 지식 품질이 높은 것은 아니다. 좋은 그래프는 필요한 문서가 필요한 만큼 연결된 상태다. 모든 문서를 서로 연결하면 그래프는 빽빽해지지만 탐색 가치는 떨어진다.

문서 리뷰 때는 그래프를 보고 다음 질문을 던진다. 기준 문서가 너무 적은가, 임시 문서가 기준 문서처럼 많은 링크를 받고 있는가, 오래된 문서가 여전히 중심에 남아 있는가. 이런 질문은 단순 검색으로는 발견하기 어렵다.

9장. 렌더러와 미리보기

렌더러는 Markdown 원문을 더 읽기 쉬운 형태로 보여준다. 이미지, 코드 블록, 다이어그램, 수식, callout, embed 같은 요소는 원문 그대로도 의미가 있지만, 적절한 미리보기가 있으면 문서를 훨씬 빠르게 이해할 수 있다.

9.1 렌더러의 공통 원칙

렌더러는 원문을 대체하지 않는다. 렌더링이 실패해도 문서는 편집 가능해야 한다. 원문 reveal 경로가 있어야 하고, 실패 상태는 사용자가 문제를 파악할 수 있을 만큼만 보여야 한다. 실패 메시지가 본문보다 과하게 튀면 안 된다.

렌더러는 긴 문서의 typing hot path를 막지 않아야 한다. 화면에 보이는 범위만 처리하거나, 문서 변경을 incrementally map하거나, 비동기 결과가 stale인지 확인해야 한다. 전체 문서를 매번 다시 스캔하는 방식은 장문에서 쉽게 한계에 닿는다.

9.2 이미지

이미지는 inline 이미지와 standalone 이미지의 요구가 다르다. 짧은 문장 안에 들어간 이미지는 작게 보여야 하고, 문단 사이에 단독으로 있는 이미지는 블록 preview가 더 자연스럽다. 아직 정책이 닫히지 않은 부분은 remote image preview와 capture 방식이다.

이미지 로딩이 실패하면 원문을 편집할 수 있어야 한다. 파일이 없거나 권한이 없거나 경로가 잘못되었을 때, 사용자는 링크를 고치거나 이미지를 다시 가져올 수 있어야 한다.

9.3 코드 블록

코드 블록은 syntax highlighting과 copy가 중요하다. 하지만 highlighting parser를 무리하게 로드하면 에디터 시작과 typing path에 부담을 줄 수 있다. 언어별 parser loading 정책은 명확해야 한다.

export function describeDocument(title: string, status: string): string {
  return `${title} is currently ${status}.`;
}

코드 블록의 copy는 fence 안쪽 코드만 복사해야 한다. 문서 전체를 문자열로 만들어 잘라내는 방식은 긴 문서에서 불필요한 비용을 만든다.

9.4 다이어그램

다이어그램은 원문과 결과물이 모두 중요하다. D2 같은 다이어그램 언어는 source를 읽으면 구조를 알 수 있고, 렌더링 결과를 보면 관계를 빠르게 이해할 수 있다.

다이어그램 렌더러는 SVG trust와 sanitization 정책이 필요하다. 외부 plugin renderer를 허용할 때는 어떤 출력을 신뢰할지, 어떤 속성을 제거할지, 실패를 어떻게 보여줄지 정해야 한다.

9.5 수식

수식은 짧은 inline 수식과 긴 display 수식으로 나뉜다. formula-heavy 문서는 렌더링 비용이 커질 수 있으므로 실제 브라우저에서 측정해야 한다. macro 정책도 중요하다. macro를 문서별로 둘지, profile로 둘지, 앱 전체 고정값으로 둘지에 따라 재현성이 달라진다.

quality_score = clarity + stability + repeatability

이 문서는 수식 렌더링을 강하게 요구하지 않고, 원문이 그대로 읽히는 짧은 예시만 둔다.

9.6 Callout

Callout은 본문 중간에서 주의, 정보, 경고를 구분할 때 유용하다. 그러나 callout이 많아지면 문서가 카드 모음처럼 보일 수 있다. 글의 흐름이 중요한 매뉴얼에서는 callout을 꼭 필요한 곳에만 사용한다.

10장. PDF 출력과 템플릿

PDF 출력은 작성 문서를 배포 가능한 고정 형태로 만드는 과정이다. Markdown 원문은 문서 내용의 기준이고, PDF 템플릿은 종이 크기, 여백, 본문 폭, header, footer, 목차 같은 조판 규칙을 담당한다.

10.1 Markdown과 조판의 분리

Markdown 본문에 PDF 전용 문법을 과하게 넣으면 문서 재사용성이 떨어진다. 가능한 한 본문은 일반 Markdown으로 유지하고, 출력 형태는 템플릿에서 관리한다. 이렇게 하면 같은 문서를 웹 문서, PDF, 내부 에디터에서 각각 다르게 보여줄 수 있다.

PDF 템플릿은 시각적 품질을 담당하지만, 본문 의미를 바꾸면 안 된다. 제목, heading, 표, 이미지, 인용 같은 구조는 Markdown에서 읽고, 템플릿은 배치와 스타일을 정한다.

10.2 템플릿 설정

템플릿에서 다룰 수 있는 설정은 페이지 크기, 방향, 여백, 단 수, header/footer, 목차 포함 여부 같은 항목이다. 고급 조판 기능은 별도 정책이 필요하다. 예를 들어 margin note, figure float, pull quote는 본문 작성 방식과 출력 방식에 모두 영향을 준다.

10.3 출력 전 점검

PDF를 만들기 전에는 링크, 이미지, 표, heading 구조를 점검한다. 웹 문서에서는 괜찮아 보이던 긴 표가 PDF에서는 페이지를 넘기며 읽기 어려울 수 있다. 반대로 PDF에서는 안정적인 페이지 구분이 웹에서는 과하게 느껴질 수 있다.

PDF는 최종 산출물에 가깝기 때문에 저장된 원문과 템플릿 상태가 명확해야 한다. 사용자는 어떤 문서를 어떤 템플릿으로 출력했는지 나중에 재현할 수 있어야 한다.

11장. Publish 문서와 Hugo 배포

Publish 문서는 사용자에게 보여줄 수 있는 기능 설명, 설정 가이드, 제약, troubleshooting을 담는다. 내부 개발 문서와 publish 문서는 역할이 다르다. 개발 문서는 결정 과정과 미결정을 담을 수 있지만, publish 문서는 사용자가 실제로 따라 할 수 있는 내용이어야 한다.

11.1 Publish 문서 작성 원칙

Publish 문서에는 구현되지 않은 계획을 shipped 기능처럼 쓰지 않는다. 계획이 필요한 경우에는 roadmap이나 내부 문서에 남기고, 사용자 문서에서는 현재 가능한 행동과 제약을 설명한다.

좋은 publish 문서는 기능을 과장하지 않는다. 사용자가 할 수 있는 것, 할 수 없는 것, 문제가 생겼을 때 확인할 것을 분명히 알려준다. 특히 설정과 파일 경로는 실제 UI와 맞아야 한다.

11.2 Hugo 섹션 구조

Hugo는 _index.md를 섹션 페이지로 사용한다. 이 문서 묶음도 content/docs/samples/_index.md 아래에 여러 샘플 문서를 둔다. 섹션 인덱스에는 해당 섹션이 무엇을 담는지, 어떤 문서를 먼저 읽으면 좋은지 적는다.

content/
  docs/
    _index.md
    samples/
      _index.md
      full-manual-long-sample.md

11.3 배포 전 검증

배포 전에는 최소한 링크, front matter, heading 구조, 코드 block fence, 표 rendering을 확인한다. 자동 검사가 있으면 좋지만, 문서의 실제 읽기 흐름은 사람이 한 번 봐야 한다.

장문 문서에서는 목차와 검색이 중요하다. 사용자는 처음부터 끝까지 읽지 않고 필요한 장으로 이동한다. heading이 의미 있게 나뉘어 있어야 한다.

12장. 문서 운영

문서는 작성보다 운영이 어렵다. 처음에는 좋은 문서였어도, 기능이 바뀌고 UI가 바뀌면 오래된 정보가 된다. 문서 운영은 오래된 정보를 줄이고, 기준 문서와 샘플 문서의 역할을 분리하는 일이다.

12.1 정기 점검

주간 점검에서는 최근 변경된 문서를 훑고, 링크가 끊겼는지, 새 기능이 publish 문서에 반영되어야 하는지 확인한다. 모든 변경을 즉시 사용자 문서에 반영할 필요는 없지만, 사용자-facing 동작이 바뀌었다면 후보로 기록해야 한다.

12.2 문서 삭제와 폐기

문서를 바로 삭제하기보다 먼저 오래됨 상태로 표시하고 대체 문서를 연결한다. 특히 외부에서 링크될 수 있는 publish 문서는 삭제가 곧 깨진 링크가 될 수 있다. 삭제가 필요하다면 redirect나 대체 안내를 검토한다.

12.3 샘플 문서 운영

샘플 문서는 실제 기능보다 앞서 나가면 안 된다. 샘플이 계획 기능을 포함해야 한다면 명확히 “계획” 또는 “점검용 원문”이라고 표시한다. 이 장문 샘플도 통합 초안이므로, 공개 매뉴얼로 쓰기 전에는 각 기능 문서로 분리하고 실제 구현 상태와 다시 맞춰야 한다.

13장. 문제 해결

문제 해결 문서는 사용자가 막혔을 때 가장 먼저 보는 문서다. 원인을 모두 설명하기보다, 사용자가 지금 할 수 있는 확인 순서를 제공해야 한다.

13.1 문서가 열리지 않을 때

문서가 열리지 않으면 먼저 파일이 실제로 존재하는지 확인한다. 다음으로 권한, 경로, 바인더 상태를 확인한다. 파일명에 특수 문자가 있거나 경로가 매우 길면 운영체제별 문제가 생길 수 있다.

확인 순서는 다음과 같이 단순해야 한다.

1. 파일이 바인더 안에 있는지 확인한다.
2. 다른 앱에서 파일을 열 수 있는지 확인한다.
3. Glif에서 바인더를 새로고침한다.
4. 문제가 반복되면 오류 메시지와 파일 경로를 기록한다.

13.2 저장이 의심될 때

저장이 의심되면 같은 문서를 다른 화면에서 다시 열기보다, 현재 화면의 저장 상태와 문서 경로를 먼저 확인한다. 충돌 가능성이 있으면 현재 본문을 잃지 않도록 복사하거나 사본으로 저장하는 흐름이 필요하다.

문서 시스템은 저장 실패를 조용히 덮어서는 안 된다. 사용자가 저장 실패를 모르고 앱을 닫으면 신뢰가 크게 깨진다.

13.3 렌더링이 실패할 때

렌더링 실패는 원문 실패와 다르다. 다이어그램이나 수식 preview가 실패해도 Markdown 본문은 살아 있어야 한다. 사용자는 원문을 reveal하고 고칠 수 있어야 한다.

렌더링 실패 메시지는 짧아야 한다. 자세한 진단은 context inspector나 별도 diagnostics에서 제공할 수 있다. 본문 안에서는 “실패했다, 다시 시도할 수 있다, 원문을 볼 수 있다” 정도면 충분하다.

14장. 검증 시나리오

이 장은 장문 테스트에서 반복해서 사용할 수 있는 시나리오를 모은다. 기능을 구현할 때마다 전체를 매번 수행할 필요는 없지만, editor hot path나 publish 변환에 영향을 주는 변경이라면 일부를 골라 수행한다.

14.1 장문 열기

1. 이 문서를 연다.
2. outline이 생성되는지 확인한다.
3. 1장, 7장, 14장, 부록으로 빠르게 이동한다.
4. 스크롤 중 본문이 끊기거나 빈 화면이 오래 남는지 본다.

14.2 중간 편집

1. 6장 표 근처에 문장을 추가한다.
2. 코드 블록 근처에 문장을 추가한다.
3. 링크가 있는 문단을 수정한다.
4. 저장 상태가 정상적으로 바뀌는지 확인한다.

14.3 IME 입력

한국어 IME 조합 중에는 명령 popup이나 preview가 끼어들지 않아야 한다. 다음 문장을 문서 중간에 입력하며 커서, 조합 문자열, 저장 상태를 확인한다.

긴 문서에서도 한국어 입력 조합이 안정적으로 유지되어야 한다.

14.4 링크와 그래프

1. 샘플 문서끼리 연결된 링크를 클릭한다.
2. 뒤로 돌아왔을 때 현재 문서 위치가 예측 가능한지 확인한다.
3. 그래프에서 이 문서와 다른 샘플 문서가 연결되는지 확인한다.
4. _index.md 포함 여부를 바꿔 섹션 문서가 어떻게 보이는지 확인한다.

15장. 나중에 분리할 문서 초안 목록

이 통합 문서는 길기 때문에 실제 매뉴얼로 쓰기 전에는 다음 문서로 나누는 것이 좋다.

15.1 분리할 때의 기준

한 문서가 너무 길어져도 문제지만, 너무 잘게 나뉘어도 사용자가 흐름을 잃는다. 분리 기준은 사용자의 목적이다. “첫 문서를 만들고 싶다”, “표를 고치고 싶다”, “PDF로 출력하고 싶다”, “문제가 생겼다”처럼 사용자의 질문이 다르면 문서를 나눈다.

15.2 링크 유지

문서를 분리할 때는 기존 링크를 유지하거나 redirect를 제공해야 한다. 장문 샘플은 내부 테스트 문서이므로 링크 변경 부담이 작지만, publish 문서는 외부 링크가 생길 수 있다. 제목과 URL을 바꾸기 전에 영향 범위를 확인한다.

부록 A. 장문 편집 관찰 노트

아래 노트는 장문 테스트에서 관찰할 항목을 반복 가능한 형태로 적은 것이다. 각 항목은 독립적으로 읽을 수 있고, 필요하면 별도 체크리스트 문서로 분리할 수 있다.

A.1 시작 속도

긴 문서를 열 때 첫 화면이 빠르게 보이는지 확인한다. 모든 heading, 그래프, preview, index를 한 번에 끝내려고 하면 시작이 늦어진다. 사용자는 먼저 본문을 보고, 보조 데이터는 뒤따라와도 된다. visible-first 원칙은 긴 문서에서 특히 중요하다.

A.2 outline 생성

Outline은 heading을 빠르게 탐색하게 해준다. 하지만 outline을 만들기 위해 매 입력마다 전체 문서를 다시 분석하면 typing path가 흔들린다. 긴 문서에서는 heading 갱신이 debounce, idle, incremental 방식으로 처리되는지 확인해야 한다.

A.3 스크롤 안정성

스크롤 중에는 DOM read와 write가 뒤섞이기 쉽다. sticky heading, fold marker, current line highlight, image resize 같은 기능이 동시에 반응하면 frame이 밀릴 수 있다. 스크롤 테스트는 천천히 움직이는 경우와 빠르게 휠을 굴리는 경우를 모두 본다.

A.4 현재 위치 감각

긴 문서에서 사용자는 지금 어느 장을 읽고 있는지 잃기 쉽다. active heading, heading path, outline highlight가 도움이 된다. 다만 이 표시가 본문 위를 덮거나, 스크롤 중 계속 깜박이면 오히려 방해가 된다.

A.5 입력 지연

입력 지연은 평균보다 tail latency가 중요하다. 대부분 빠르다가 가끔 500ms 멈추면 사용자는 에디터를 신뢰하기 어렵다. 장문 테스트에서는 평범한 문단, 표 근처, 코드 블록 근처, 링크 많은 문단, 문서 끝에서 각각 입력해 본다.

A.6 저장 루프

저장 루프는 같은 내용이 반복 저장되는 문제다. fold session, scroll position, layout state 같은 보조 상태가 매번 바뀐 것으로 판단되면 저장이 계속 발생할 수 있다. 저장 요청 수와 실제 변경 수가 크게 다르면 원인을 확인해야 한다.

A.7 링크 preview

링크 preview는 hover path에 있다. hover는 사용자가 의도하지 않아도 자주 발생하므로 비용이 낮아야 한다. preview load가 늦게 도착했을 때 현재 문서, link occurrence, binder path가 바뀌었으면 결과를 버려야 한다.

A.8 이미지 preview

이미지가 많은 문서에서는 resize observer와 asset resolver 비용이 누적될 수 있다. 한 이미지마다 observer를 만들면 긴 문서에서 비용이 커진다. 공유 observer, cache hit, stale discard metric을 확인한다.

A.9 다이어그램 preview

다이어그램은 비동기 렌더링이 많다. source가 바뀐 뒤 이전 렌더 결과가 도착하면 stale 결과를 버려야 한다. SVG output은 sanitizer를 통과해야 하고, 실패해도 원문을 편집할 수 있어야 한다.

A.10 수식 preview

수식은 짧은 문서에서는 문제가 없어도 formula-heavy 문서에서는 비용이 커질 수 있다. visible range 안의 수식만 렌더링하는지, macro policy가 재현성을 해치지 않는지 확인한다.

A.11 표 interaction

표는 마우스, 키보드, selection, menu, resize가 모두 섞인다. dense table 문서에서는 hover와 resize가 typing path를 막지 않는지 확인한다. 표 편집은 본문 편집의 일부지만, 문서 전체를 표 계산 때문에 멈추게 해서는 안 된다.

A.12 코드 fence

코드 fence는 원문 marker와 body를 구분해야 한다. fold range가 marker line까지 숨기면 사용자가 source boundary를 잃을 수 있다. empty fence affordance는 도움이 되지만, 긴 whitespace-only fence를 매번 스캔하면 안 된다.

A.13 인용과 callout

인용과 callout은 줄 단위 구조를 가진다. selection이 인용 marker와 본문을 걸칠 때 source reveal이 예측 가능해야 한다. callout이 nested Markdown을 포함할 경우, 내부 목록과 코드 블록이 올바르게 유지되는지 확인한다.

A.14 검색

긴 문서에서는 검색이 중요하다. 검색은 결과 수가 많아도 editor input을 막지 않아야 한다. 검색 결과 highlight와 current selection highlight가 충돌하지 않는지 확인한다.

A.15 그래프 반영

문서 링크가 그래프에 반영되는 시점은 사용자 기대와 맞아야 한다. 저장 전 초안 링크를 즉시 반영할지, 저장 후 반영할지 정책이 필요하다. 장문 테스트에서는 링크 추가 후 그래프 갱신이 과하게 비싸지 않은지 확인한다.

A.16 publish 변환

Publish 변환은 문서 원문, front matter, 링크, 리소스, theme style을 함께 다룬다. 긴 문서 하나 때문에 변환 전체가 실패하면 원인을 찾기 어렵다. 변환 로그와 실패 위치가 충분히 좁혀져야 한다.

A.17 PDF 변환

PDF 변환은 페이지 단위 layout이 들어가므로 웹 preview와 다른 문제가 생긴다. 긴 표, 긴 코드 블록, 긴 heading, 많은 링크가 PDF에서 어떻게 줄바꿈되는지 확인한다.

A.18 문서 분리

통합 문서를 실제 매뉴얼로 쓰려면 장별로 나눠야 한다. 분리할 때 각 장의 첫 문단이 독립 문서의 intro가 될 수 있는지 확인한다. 이 샘플은 그 기준을 테스트하기 위해 각 장의 목적 문단을 의도적으로 남겨 둔다.

A.19 오래된 정보

오래된 정보는 잘못된 정보보다 위험할 수 있다. 사용자는 문서가 공식처럼 보이면 그대로 따른다. 따라서 publish 문서의 계획 문구는 조심해야 한다. 구현되지 않은 기능은 내부 문서나 roadmap에 두고, publish에는 검증된 행동만 둔다.

A.20 샘플의 역할

샘플 문서는 기능을 검증하는 동시에 좋은 작성 예시가 되어야 한다. 무작위 텍스트는 성능 테스트에는 쓸 수 있지만, 장기적으로 문서 품질 테스트에는 도움이 적다. 이 문서는 실제 운영 문서로도 일부 재사용할 수 있도록 구성한다.

부록 B. 장문 수동 점검 기록지

아래 표는 실제 테스트를 수행한 뒤 결과를 적기 위한 기록지다. 이 표는 나중에 별도 QA 문서로 분리할 수 있다.

B.1 관찰 템플릿

## 장문 테스트 기록

- 문서:
- 환경:
- 입력 방식:
- 확인한 장:
- 느린 구간:
- 깨진 링크:
- 렌더링 실패:
- 저장 상태:
- 후속 작업:

B.2 완료 기준

장문 테스트의 완료 기준은 “아무 문제가 없다”가 아니다. 문제가 있더라도 원인이 기록되고, 사용자가 문서를 잃지 않으며, 다음 수정 항목이 분리되어 있으면 테스트는 의미가 있다. 성능 문제는 수치와 재현 경로가 있어야 고칠 수 있다.

부록 C. 기능별 분리 초안

이 부록은 통합 매뉴얼을 실제 사용자 문서로 분리할 때 각 문서의 첫 초안으로 쓸 수 있는 내용을 모은다. 장문 테스트에서는 heading 수, 중첩 깊이, 반복되는 링크, 긴 문단, 표 사이의 스크롤 안정성을 확인하는 역할도 한다.

C.1 시작하기 문서 초안

시작하기 문서는 사용자가 첫 바인더를 만들고 첫 문서를 저장하는 데 집중해야 한다. 처음부터 그래프, PDF, 테마, 고급 표 편집을 모두 설명하면 사용자는 핵심 흐름을 놓친다. 시작하기 문서의 목적은 “문서를 만들고 다시 열 수 있다”는 확신을 주는 것이다.

시작하기 문서에는 다음 순서를 권장한다.

1. 새 바인더를 만든다.
2. 첫 문서를 만든다.
3. 제목과 첫 문단을 쓴다.
4. 저장 상태를 확인한다.
5. 앱이나 화면을 다시 열어 문서가 남아 있는지 확인한다.

이 문서는 짧아야 한다. 사용자가 첫 문서를 쓰기 전에 많은 개념을 배워야 한다면 온보딩은 실패한 것이다. 복잡한 설명은 관련 문서로 연결하고, 시작하기 본문은 실제 행동 순서만 남긴다.

C.2 문서 작성 기본 문서 초안

문서 작성 기본 문서는 제목, heading, 문단, 목록, 인용, 코드 블록, 링크를 설명한다. 이 문서는 Markdown 문법 레퍼런스가 아니라 Glif에서 어떻게 쓰면 좋은지를 설명해야 한다. 예를 들어 heading 문법 자체보다, 긴 문서에서 heading을 어떻게 나누면 outline이 유용한지를 설명하는 편이 낫다.

본문은 “짧은 원칙 -> 예시 -> 주의할 점” 구조가 좋다. 사용자는 문법을 외우고 싶어 하지 않는다. 지금 쓰는 문서에서 어떤 형식을 선택해야 할지 알고 싶어 한다. 따라서 각 섹션에는 잘 쓰는 예시와 피해야 할 예시를 함께 둔다.

## 좋은 heading

현재 장의 목적을 직접 말한다.

## 애매한 heading

기타, 참고, 내용, 정리 같은 말만 쓰면 나중에 찾기 어렵다.

C.3 명령 문서 초안

명령 문서는 Slash Command와 Block Inserter를 함께 설명한다. 두 표면은 같은 command registry를 쓰므로 사용자에게도 “같은 명령을 여는 두 가지 방법”으로 설명하는 것이 자연스럽다. 키보드 중심 사용자는 slash를 쓰고, 마우스나 current block 중심 사용자는 block inserter를 쓸 수 있다.

명령 문서에서 중요한 것은 명령이 열리지 않는 경우를 설명하는 것이다. 코드 블록, inline code, IME composition, 다중 선택 중에는 명령이 제한될 수 있다. 이것은 오류가 아니라 원문과 입력을 보호하기 위한 동작이다.

C.4 표 편집 문서 초안

표 편집 문서는 기본 표 삽입, 셀 이동, 행과 열 추가, 정렬, 병합, 선택 범위 차트 참조를 순서대로 설명한다. 표는 설명할 기능이 많으므로 한 페이지에 모든 세부 동작을 넣으면 길어진다. 실제 사용자 문서에서는 “기본 편집”, “선택과 병합”, “차트 참조”, “제약”으로 나누는 것이 좋다.

표 문서에서 반드시 설명해야 할 원칙은 Markdown 원문 보존이다. 사용자는 병합이나 열 너비가 Markdown 원문에 어떻게 저장되는지 궁금해할 수 있다. 원문에는 기본 table이 남고, 일부 표시 설정은 문서별 profile로 저장된다고 설명하면 외부 도구와의 관계를 이해하기 쉽다.

C.5 링크와 참조 문서 초안

링크 문서는 일반 Markdown 링크와 wiki 스타일 링크를 구분해야 한다. 일반 링크는 배포와 외부 도구 호환성에 강하고, wiki 링크는 빠른 내부 작성에 좋다. 사용자는 둘 중 하나만 써야 하는 것이 아니라 상황에 맞게 선택할 수 있어야 한다.

참조 문서에서는 링크 미리보기, 링크 이동, 깨진 링크 처리, 문서 rename 이후 링크 점검을 다룬다. 링크는 문서 구조의 핵심이므로, 단순 편집 기능이 아니라 운영 기준으로 설명하는 것이 좋다.

C.6 지식 그래프 문서 초안

지식 그래프 문서는 그래프를 멋진 시각화로 소개하기보다, 어떤 질문에 답할 수 있는지로 설명해야 한다. 고립 문서를 찾는지, 중심 문서를 찾는지, 섹션 구조를 확인하는지에 따라 그래프 설정이 달라진다.

그래프 문서에는 _index.md 포함 설정을 꼭 설명한다. 작성자 관점에서는 _index.md가 노이즈일 수 있지만, 배포 구조 관점에서는 중요한 문서다. 같은 그래프라도 목적에 따라 표시 기준이 달라질 수 있다는 점을 알려야 한다.

C.7 렌더러 문서 초안

렌더러 문서는 “보이는 결과가 원문을 대체하지 않는다”는 원칙을 앞에 둔다. 이미지, 코드, 다이어그램, 수식, callout, embed는 모두 source-safe preview의 변형이다. 실패해도 원문 편집이 가능해야 하고, 원문 reveal 경로가 있어야 한다.

렌더러 문서는 renderer별 세부 기능보다 공통 동작을 먼저 설명하는 편이 좋다. Loading, failure, retry, reveal source, cache, stale result 같은 개념을 공통으로 이해하면 사용자는 특정 preview가 실패했을 때 당황하지 않는다.

C.8 PDF 출력 문서 초안

PDF 출력 문서는 “원문 작성”과 “출력 조판”을 구분해야 한다. 사용자는 Markdown 본문을 고치면 PDF 내용이 바뀌고, 템플릿을 고치면 PDF의 형태가 바뀐다는 모델을 이해해야 한다. 둘을 섞어 설명하면 문제가 생겼을 때 어디를 고쳐야 하는지 알기 어렵다.

PDF 문서에는 출력 전 체크리스트가 필요하다. 제목, 목차, 긴 표, 이미지 경로, header/footer, 페이지 번호, 링크를 확인하는 순서를 제공한다. PDF는 고정 산출물이기 때문에 웹 preview보다 더 꼼꼼한 확인이 필요하다.

C.9 Publish 문서 문서 초안

Publish 문서는 내부 문서와 다르다. 내부 문서는 미결정, 실험, 리뷰 결과를 담을 수 있지만, publish 문서는 사용자가 따라 할 수 있는 현재 동작을 설명해야 한다. 따라서 publish 문서에는 “계획”을 쓸 때 특히 조심해야 한다.

Publish 문서 작성자는 다음 질문을 확인한다.

• 이 기능은 현재 사용자가 실제로 쓸 수 있는가?
• 메뉴 이름과 설정 이름이 실제 UI와 맞는가?
• 제약을 숨기지 않았는가?
• 오류가 생겼을 때 사용자가 할 수 있는 다음 행동이 있는가?
• 내부 구현 세부사항을 사용자에게 불필요하게 노출하지 않았는가?

C.10 문제 해결 문서 초안

문제 해결 문서는 원인 분석 보고서가 아니라 행동 순서다. 사용자는 문제가 생긴 상태에서 긴 배경 설명을 읽기 어렵다. 먼저 증상별로 확인할 것을 제공하고, 더 자세한 설명은 아래에 둔다.

문제 해결 문서는 다음 형태가 좋다.

## 증상

문서가 열리지 않는다.

## 먼저 확인할 것

1. 파일이 존재하는지 확인한다.
2. 권한이 있는지 확인한다.
3. 바인더를 새로고침한다.

## 계속 실패하면

오류 메시지, 파일 경로, 재현 순서를 기록한다.

부록 D. 장문 성능 테스트 패턴

이 부록은 장문 성능 테스트에서 반복해서 사용할 수 있는 입력 패턴을 설명한다. 각 패턴은 실제 사용자 문서에서도 나타날 수 있는 형태를 기준으로 한다. 무작위 텍스트보다 실제 문서 패턴이 더 유용한 이유는, 렌더러와 parser가 단순 길이뿐 아니라 구조의 밀도에 영향을 받기 때문이다.

D.1 Plain prose dense

Plain prose dense 문서는 heading은 적고 문단이 길다. 소설, 에세이, 회고, 제품 전략 문서에서 자주 나타난다. 이런 문서는 렌더러보다 selection, current line, paragraph scan, search 비용을 보기 좋다. 문단이 길면 현재 문단 계산이 멀리 걸어갈 수 있으므로 blank line 기준과 scan cap이 중요해진다.

테스트할 때는 긴 문단의 앞, 중간, 끝에 각각 입력한다. 줄바꿈이 없는 긴 문단에서 selection을 만들고, 현재 줄 highlight와 paragraph context가 과하게 넓게 반응하지 않는지 확인한다.

D.2 Heading dense

Heading dense 문서는 짧은 heading이 많다. API 문서, 매뉴얼, release note, 정책 문서에서 나타난다. 이런 문서는 outline, active heading, heading path, heading jump, graph indexing 비용을 보기 좋다.

Heading dense 테스트에서는 outline이 너무 늦게 갱신되지 않는지, heading을 수정했을 때 active heading이 stale 상태로 오래 남지 않는지 확인한다. full authority가 필요한 작업은 background에서 수행되어도 되지만, 사용자가 현재 위치를 잃으면 안 된다.

D.3 Link dense

Link dense 문서는 많은 내부 링크와 외부 링크를 가진다. 지식 베이스, ADR, 제품 매뉴얼에서 흔하다. 링크가 많으면 link hover, preview, graph indexing, broken link check가 모두 영향을 받는다.

테스트에서는 링크 위를 빠르게 지나가고, 일부 링크를 클릭하고, 링크 텍스트를 수정한다. hover preview가 늦게 도착했을 때 현재 occurrence가 바뀌면 버려지는지 확인한다.

D.4 Table dense

Table dense 문서는 작은 표가 많거나, 큰 표가 몇 개 있는 형태다. 운영 체크리스트, 가격표, 기능 매트릭스, QA 기록에서 흔하다. 표는 DOM plugin과 selection이 복잡하므로 실제 브라우저 측정이 중요하다.

테스트에서는 표 위아래 본문 입력, 셀 이동, 범위 선택, 행 추가, 열 너비 조정, 메뉴 열기를 확인한다. 표 기능은 편리하지만 일반 본문 입력을 막아서는 안 된다.

D.5 Renderer dense

Renderer dense 문서는 이미지, 다이어그램, 수식, code block, embed가 많이 들어 있다. 튜토리얼, 기술 문서, 연구 노트에서 흔하다. 렌더러는 async, cache, widget lifecycle, DOM measurement가 모두 얽히므로 장문 테스트에서 반드시 분리해 봐야 한다.

테스트에서는 스크롤로 renderer를 viewport 밖으로 보냈다가 다시 들여오고, source를 수정한 뒤 이전 async 결과가 도착하는 상황을 본다. stale result가 DOM을 덮어쓰면 안 된다.

D.6 IME dense

IME dense 문서는 한국어, 일본어, 중국어처럼 조합 입력이 많은 문서다. IME 테스트는 단순 typing latency와 다르다. 조합 중인 글자를 preview나 command trigger가 방해하면 사용자는 입력이 깨졌다고 느낀다.

테스트에서는 slash가 들어간 문장, 링크 marker 근처, 표 셀 안, 코드 블록 주변에서 한국어를 입력한다. 조합 중 command popup이 열리지 않는지, 저장이나 decoration update가 조합 문자열을 흔들지 않는지 확인한다.

D.7 Mixed authoring

Mixed authoring 문서는 실제 작업 문서에 가장 가깝다. heading, 본문, 표, 링크, 코드, 인용, 이미지가 적당히 섞여 있다. 모든 기능이 조금씩 있기 때문에 특정 bottleneck을 찾기는 어렵지만, 사용자가 실제로 느끼는 품질을 보기 좋다.

Mixed 테스트는 release 전 smoke로 적합하다. 문서 중간에서 여러 종류의 편집을 짧게 수행하고, 저장 상태와 UI 반응을 본다. 문제를 발견하면 더 좁은 dense 패턴으로 재현한다.

D.8 External change

External change 테스트는 Glif 밖에서 파일이 바뀌었을 때의 동작을 본다. 저장 중인 문서와 외부 변경이 충돌하면 사용자는 어떤 내용이 기준인지 알아야 한다. 긴 문서에서는 diff나 conflict 안내도 느릴 수 있다.

테스트에서는 문서를 열어 둔 상태에서 외부 편집기로 파일을 바꾸고, Glif가 어떻게 알리는지 확인한다. 자동으로 덮어쓰지 않고 사용자가 선택할 수 있어야 한다.

D.9 Restore session

Restore session 테스트는 앱을 닫았다가 다시 열었을 때 active document, scroll, fold, outline, panel 상태가 어떻게 복원되는지 본다. 긴 문서에서는 맨 위로 돌아가는 것만으로도 큰 불편이 된다.

복원은 완벽할 필요는 없지만 예측 가능해야 한다. 복원할 수 없는 상태라면 안전한 기본 위치로 이동하고, 문서 내용은 반드시 보존되어야 한다.

D.10 Publish transform

Publish transform 테스트는 긴 Markdown이 Hugo content로 들어갔을 때 front matter, links, code fences, section index가 깨지지 않는지 본다. 배포 변환은 문서 수가 많아질수록 실패 위치를 찾기 어려워진다.

테스트에서는 이 문서처럼 긴 샘플을 포함한 상태에서 publish 관련 검사를 돌린다. 실패하면 문서 길이 때문인지, 특정 Markdown 구조 때문인지, 링크 경로 때문인지 나눠 봐야 한다.

부록 E. 수동 QA 시나리오 상세

이 부록은 사람 손으로 확인해야 하는 시나리오를 더 자세히 적는다. 자동 테스트는 빠르고 반복 가능하지만, 작성 표면의 조용함, visual hierarchy, 입력 리듬은 사람이 봐야 하는 부분이 남는다.

E.1 첫 화면 관찰

문서를 열고 3초 동안 아무것도 누르지 않는다. 첫 화면에 본문이 먼저 보이는지, 보조 패널이 과하게 강조되지 않는지, loading 표시가 남아 있지 않은지 확인한다. 긴 문서에서 첫 화면이 안정적으로 보이면 사용자는 나머지 background 작업을 기다릴 수 있다.

관찰 메모에는 화면이 비어 있던 시간, outline이 생긴 시점, 저장 상태 표시, 에러 toast 유무를 적는다. 수치가 없더라도 반복 관찰하면 어느 변경에서 품질이 나빠졌는지 찾을 수 있다.

E.2 빠른 스크롤

마우스 휠이나 트랙패드로 빠르게 문서를 끝까지 내렸다가 다시 올린다. 중간에 렌더러가 많은 구간, 표가 많은 구간, heading이 많은 구간에서 멈춘다. 빈 공간이 오래 보이거나, 위치가 갑자기 튀거나, hover affordance가 스크롤 중 과하게 남는지 본다.

빠른 스크롤은 실제 사용자가 긴 문서에서 특정 부분을 찾을 때 자주 발생한다. 스크롤 중 모든 preview를 완벽히 렌더링하려고 하기보다, 화면과 입력이 안정적인 것이 우선이다.

E.3 느린 읽기

문서를 천천히 읽으며 heading path와 outline highlight가 현재 위치를 잘 따라오는지 확인한다. 너무 늦게 바뀌면 위치 감각이 떨어지고, 너무 민감하게 바뀌면 읽는 중 표시가 흔들린다.

느린 읽기 시나리오는 visual polish를 보기 좋다. 문단 폭, 줄 간격, 배경, 선택 색, current line 표시가 긴 시간 읽어도 피곤하지 않은지 확인한다.

E.4 중간 삽입

문서 중간 heading 아래에 새 문단을 삽입한다. 이때 outline, active heading, 저장 상태, graph indexing이 어떻게 반응하는지 본다. 중간 삽입은 offset mapping과 range cache가 제대로 작동하는지 확인하기 좋다.

삽입 후 바로 undo/redo를 반복한다. undo/redo는 문서 내용뿐 아니라 selection과 scroll 느낌도 중요하다. 사용자가 방금 한 작업을 되돌린다고 느껴야 한다.

E.5 표 주변 편집

표 바로 위와 아래에서 문장을 입력한다. 그 다음 표 셀 안에 들어가 값을 고치고 다시 본문으로 나온다. 표 편집 모드가 본문 편집 모드와 충돌하지 않는지 확인한다.

표 선택 후 문서의 다른 영역을 클릭했을 때 selection이 안전하게 정리되는지도 본다. 표 selection이 남아 일반 명령에 영향을 주면 사용자는 예측하기 어렵다.

E.6 코드 블록 주변 편집

코드 블록의 언어 이름을 바꾸고, 본문을 수정하고, copy 동작을 확인한다. 코드 fence marker line과 body line의 역할이 분명해야 한다. fold를 적용해도 source boundary를 잃지 않아야 한다.

코드 블록 안에서 slash나 block inserter가 열리지 않는지 확인한다. 코드 안의 문자는 명령이 아니라 source다.

E.7 링크 hover

링크 위에 커서를 올리고 preview가 뜨기 전에 빠르게 다른 링크로 이동한다. 이전 preview가 늦게 도착해 현재 링크 위에 표시되면 안 된다. 링크 preview는 source occurrence identity를 기준으로 stale 여부를 확인해야 한다.

링크 텍스트를 수정한 직후 hover를 반복한다. 같은 URL이라도 occurrence가 달라졌다면 이전 결과를 조심해야 한다.

E.8 임베드 실패

존재하지 않는 문서를 참조하는 embed 원문을 만든다. 실패 상태가 본문을 과하게 밀어내지 않는지, retry와 reveal source가 가능한지 확인한다. 실패한 preview 때문에 typing이 느려지면 안 된다.

실패 상태는 지역화와 accessibility도 확인해야 한다. 버튼 이름이 명확하고, keyboard로 접근할 수 있어야 한다.

E.9 저장과 닫기

문서를 수정한 뒤 바로 닫거나 다른 문서로 이동한다. background save, blur save, manual save의 구분이 안전한지 확인한다. 저장되지 않은 변경이 있을 때 사용자가 알 수 있어야 한다.

긴 문서에서는 저장 materialization 비용이 커질 수 있다. 저장이 필요한 시점에만 전체 문자열을 만드는지, 매 입력마다 만들지 않는지 metric으로 확인한다.

E.10 배포 미리보기

문서를 publish content로 포함한 뒤 로컬 배포 미리보기를 확인한다. section navigation, heading anchor, code block, table, relative link가 깨지지 않는지 본다. 긴 문서에서는 페이지 목차가 너무 길어질 수 있으므로, 실제 공개 전에는 분리가 필요하다.

부록 F. 용어집

이 용어집은 사용자 문서와 내부 문서 사이에서 자주 쓰는 말을 정리한다. 실제 공개 용어집으로 쓰려면 더 짧고 사용자 친화적으로 다듬어야 한다.

F.1 Markdown source of truth

문서의 기준 내용이 Markdown 원문이라는 뜻이다. Glif가 편집을 돕기 위해 preview나 projection을 보여줄 수 있지만, 본문 자체는 사람이 읽을 수 있는 Markdown으로 남아야 한다.

F.2 Projection

원문을 다른 방식으로 보여주는 표현이다. 표를 셀처럼 보여주거나, 링크 preview를 보여주거나, 다이어그램 source를 그림으로 보여주는 것이 projection에 해당한다. Projection은 원문을 대체하지 않는다.

F.3 Profile

문서별 표시 설정을 저장하는 보조 데이터다. Markdown 문법만으로 표현하기 어려운 열 너비, 병합, 일부 render mode 같은 정보를 담을 수 있다. Profile은 원문 내용을 대신하지 않고 표시 방식을 보조한다.

F.4 Renderer

Markdown 원문 일부를 읽기 쉬운 형태로 보여주는 구성요소다. 이미지, 코드, 다이어그램, 수식, embed preview가 renderer에 해당한다. Renderer는 실패해도 원문 편집을 막지 않아야 한다.

F.5 Hot path

사용자가 입력하거나 스크롤하거나 hover하는 동안 즉시 반응해야 하는 경로다. Hot path에 전체 문서 scan이나 무거운 async 결과 처리가 들어가면 긴 문서에서 지연이 생긴다.

F.6 Available tree

현재 frame에서 이미 준비된 syntax tree 범위를 의미한다. 긴 문서에서 전체 parse를 강제하지 않고, 사용 가능한 범위 안에서 정보를 얻는 방식은 typing path를 보호하는 데 도움이 된다.

F.7 Full authority

문서 전체를 확실히 분석한 결과를 의미한다. Outline publish, indexing, reference definition resolution처럼 전체 문서 정확도가 필요한 작업은 full authority가 필요할 수 있다. 다만 이런 작업은 일반 입력 frame 밖에서 처리해야 한다.

F.8 Stale result

비동기 작업이 시작된 뒤 문서나 selection이나 target이 바뀌어 더 이상 현재 상태에 적용하면 안 되는 결과다. Preview, image load, diagram render, embed load에서 stale result를 버리는 정책이 중요하다.

F.9 Reveal source

렌더링된 표면 뒤의 Markdown 원문을 사용자가 다시 볼 수 있게 하는 동작이다. Source-safe renderer에서는 reveal source가 매우 중요하다. 사용자가 원문을 고칠 수 있어야 문제를 해결할 수 있다.

F.10 Quiet writing surface

글쓰기 중 보조 UI가 본문보다 더 강하게 반응하지 않는 작성 표면이다. 조용하다는 것은 정보가 없다는 뜻이 아니라, 필요한 정보가 적절한 강도로 표시된다는 뜻이다.

부록 G. 장문 샘플 자체 점검

이 부록은 이 문서가 장문 테스트 샘플로 적합한지 확인하는 자체 점검 항목이다. 실제 테스트 문서도 시간이 지나면 목적을 잃을 수 있으므로, 샘플 문서 자체를 주기적으로 점검해야 한다.

G.1 구조 점검

이 문서는 1장부터 15장까지의 본문과 여러 부록으로 구성된다. Outline이 너무 복잡해지면 실제 매뉴얼로는 부적합하지만, 장문 테스트에서는 heading이 충분히 많아야 한다. 따라서 이 샘플은 일반 사용자 문서보다 heading이 많다.

구조 점검 시에는 heading level이 갑자기 건너뛰지 않는지, 각 장이 독립 문서로 분리될 수 있는지, 부록이 본문보다 지나치게 중요한 내용을 숨기고 있지 않은지 확인한다.

G.2 링크 점검

이 문서는 다른 샘플 문서와 기존 publish 문서로 연결된다. 링크는 장문 테스트에서 hover, click, graph indexing을 확인하는 데 필요하다. 링크가 깨지면 테스트 문서의 가치가 떨어지므로, 파일을 이동할 때 상대 경로를 함께 갱신해야 한다.

G.3 렌더링 점검

이 문서는 표, 코드 block, YAML block, JSON block, D2 block, 인용, 체크리스트를 포함한다. 이미지 파일은 의도적으로 포함하지 않는다. missing asset 때문에 테스트가 불안정해지는 것을 피하기 위해서다. 이미지 테스트는 별도 리소스가 준비된 문서에서 수행하는 편이 낫다.

G.4 길이 점검

이 문서는 50,000자 이상의 장문 테스트를 목표로 한다. 길이는 성능 테스트의 한 조건일 뿐이다. 같은 50,000자라도 heading이 많은 문서, 표가 많은 문서, 렌더러가 많은 문서는 서로 다른 비용을 만든다. 따라서 이 문서는 통합 smoke이고, 병목 분석에는 별도 dense 샘플이 필요하다.

G.5 공개 적합성 점검

이 문서는 publish tree 안에 있지만 실제 공개 매뉴얼 확정본은 아니다. 공개 전에 계획성 문구, 내부 용어, 검증 기준, 미완성 정책을 제거하거나 별도 내부 문서로 옮겨야 한다. 사용자에게 보여줄 문서는 “지금 할 수 있는 행동”을 중심으로 다시 다듬는다.

G.6 분리 후 유지

나중에 이 문서를 여러 문서로 분리하더라도, 장문 테스트용 통합 문서는 유지하는 편이 좋다. 실제 사용자 문서는 짧아지는 것이 맞지만, 에디터 성능과 publish 변환을 테스트하려면 일부러 긴 문서가 필요하다. 분리 후에는 이 문서를 “장문 회귀 샘플”로 축소하거나, 자동 생성하지 않는 evergreen 샘플로 유지한다.

부록 H. 긴 문서 작성 예시 단락

아래 단락들은 긴 문서에서 일반 prose가 이어질 때 읽기 폭, 줄 높이, selection, search, current line 표시를 확인하기 위한 예시다. 내용은 문서 운영 원칙을 반복적으로 다루지만, 각 단락이 독립적으로도 의미를 갖도록 작성한다.

문서는 도구의 기능을 보여주는 전시물이 아니라, 다음 작업을 가능하게 하는 운영 자산이다. 작성자는 지금 알고 있는 사실을 모두 적고 싶어 하지만, 독자는 지금 필요한 행동을 찾고 싶어 한다. 좋은 매뉴얼은 이 둘 사이에서 균형을 잡는다. 충분한 맥락을 제공하되, 독자가 길을 잃지 않도록 제목과 목록과 예시를 적절히 배치한다.

긴 문서에서 가장 중요한 것은 한 번에 모든 것을 기억하게 만들지 않는 것이다. 사용자는 목차를 보고 필요한 장으로 이동하고, 장의 첫 문단을 읽고 계속 읽을지 결정한다. 따라서 각 장의 첫 문단은 독립적으로 의미가 있어야 한다. “앞에서 설명한 것처럼”으로 시작하는 문단은 분리 후 문서에서 약해진다.

문서가 오래 유지되려면 변경 비용이 낮아야 한다. 같은 설명이 여러 곳에 있으면 작은 기능 변경도 큰 문서 작업이 된다. 반복 설명이 필요한 경우에는 핵심 정의를 한곳에 두고, 다른 곳에서는 링크로 연결한다. 링크는 독자의 흐름을 끊을 수 있지만, 오래된 중복 설명보다는 낫다.

표는 비교를 빠르게 만들지만, 긴 설명을 표 안에 넣으면 읽기 어렵다. 표의 각 셀은 짧고 서로 비교 가능한 값이어야 한다. 문장으로 풀어야 할 내용은 표 아래 문단으로 옮긴다. 장문 테스트에서는 표가 많은 구간과 문단이 긴 구간을 모두 포함해 각 렌더링 경로가 안정적인지 확인한다.

코드 블록은 정확성이 중요하다. 사용자가 복사할 수 있는 예시는 실제로 동작하거나, 동작하지 않는 예시라면 의도적으로 pseudo code라고 표시해야 한다. 설정 예시는 현재 UI와 맞아야 한다. 오래된 설정 이름이 남아 있으면 사용자는 문서보다 제품을 의심하게 된다.

렌더링은 편집을 돕기 위한 것이다. 렌더링 결과가 아름다워도 원문을 고칠 수 없으면 작성 도구로서는 부족하다. 특히 긴 문서에서는 렌더링 실패가 일부 구간에만 생겨도 전체 문서 작성이 막히면 안 된다. 실패는 지역적으로 표시되고, 본문 입력은 계속 가능해야 한다.

그래프는 문서의 관계를 보여주지만, 그래프가 모든 구조를 설명해 주지는 않는다. 좋은 문서 구조는 파일명, heading, 링크, 섹션 인덱스가 함께 만든다. 그래프는 이 구조를 검토하는 도구다. 그래프가 복잡해졌다면 링크를 줄여야 하는지, 문서를 나눠야 하는지, 기준 문서를 더 명확히 해야 하는지 검토한다.

배포 문서는 내부 문서보다 더 엄격해야 한다. 내부 문서에는 실험과 계획과 미결정이 들어갈 수 있지만, 배포 문서는 사용자가 따라 할 수 있는 현재 동작을 설명해야 한다. 계획을 공개 문서에 쓰려면 명확히 계획이라고 표시해야 하고, 가능하면 roadmap 영역으로 분리한다.

장문 샘플은 실제 문서 품질을 해치지 않으면서 성능 테스트에 충분한 길이를 제공해야 한다. 의미 없는 반복 문자열은 parser와 렌더러의 일부 비용을 볼 수 있지만, 실제 사용자가 만드는 문서의 구조를 재현하지 못한다. 이 샘플은 문단, 표, 링크, 코드, 부록, 체크리스트가 섞인 형태로 유지한다.

마지막으로, 문서 테스트는 한 번으로 끝나지 않는다. 제품이 바뀌고, 에디터가 바뀌고, 배포 방식이 바뀌면 같은 샘플을 다시 열어 봐야 한다. 긴 문서는 회귀를 발견하기 좋은 도구다. 작은 문서에서는 보이지 않던 저장 루프, scroll 지연, stale preview, outline 갱신 문제가 긴 문서에서 드러날 수 있다.

부록 I. 전체 기능 매뉴얼 확장 초안

이 부록은 실제 전체 기능 매뉴얼로 분리할 때 빠지기 쉬운 장을 미리 적어 둔다. 일부 내용은 이미 앞 장에서 다룬 원칙을 다른 사용자 질문 형태로 다시 설명한다. 장문 테스트 관점에서는 반복되는 의미 구조, 비슷한 heading, 긴 문단, 표와 목록이 섞인 구간에서 editor와 publish 변환이 안정적인지 확인하는 역할을 한다.

I.1 문서 탐색 패턴

사용자는 문서를 항상 왼쪽에서 오른쪽, 위에서 아래로 읽지 않는다. 어떤 사용자는 검색으로 들어오고, 어떤 사용자는 그래프에서 들어오고, 어떤 사용자는 링크 preview를 보고 들어온다. 따라서 문서의 각 장은 독립적인 진입점이 될 수 있어야 한다. “이전 장에서 말한 것처럼”이라는 표현은 통합 문서에서는 자연스럽지만, 분리된 문서에서는 약해질 수 있다.

탐색 패턴을 고려한 문서는 첫 문단에 목적을 두고, 중간에 예시를 두고, 끝에 다음 행동을 둔다. 사용자가 검색 결과에서 바로 중간 heading으로 들어와도 최소한의 맥락을 얻을 수 있어야 한다. 긴 문서 테스트에서는 검색 결과에서 특정 heading으로 이동한 뒤 outline과 scroll 위치가 맞는지 확인한다.

I.2 작업 공간과 문서 표면

작업 공간은 문서를 둘러싼 도구의 배치다. Shelf, outline, info zone, preview, graph는 모두 도움이 되지만, 글을 쓰는 순간에는 본문 표면이 중심이어야 한다. 작업 공간이 강력할수록 사용자는 많은 일을 한 화면에서 할 수 있지만, 동시에 본문에 집중하기 어려워질 수 있다.

전체 매뉴얼에서는 작업 공간을 “항상 켜야 하는 것”으로 설명하지 않는다. 사용자는 필요할 때 패널을 열고, 끝나면 닫거나 접을 수 있어야 한다. 좋은 기본값은 초심자에게 조용하고, 숙련자에게 충분히 확장 가능해야 한다.

I.3 정보 영역의 역할

Info zone은 선택한 대상의 자세한 설정을 다루는 곳이다. 표를 선택하면 표 설정을, 이미지를 선택하면 이미지 정보를, 렌더러를 선택하면 진단이나 source reveal을 보여줄 수 있다. Info zone은 본문 위에 모든 것을 띄우는 대신, 문맥 정보를 안정적으로 제공하는 표면이다.

Info zone 문서는 기능별 설정을 모두 반복하기보다, “선택한 대상의 설정은 본문 옆에서 확인한다”는 모델을 먼저 설명하는 편이 좋다. 각 기능 문서에서는 해당 기능의 info zone 항목만 짧게 설명하고, 공통 조작은 Info zone 문서로 연결한다.

I.4 Action bar와 명령 표면

Action bar는 현재 표면에서 가능한 명령을 보여준다. 문서 히스토리, PDF preview, table info, graph 같은 표면마다 action bar가 있을 수 있다. 중요한 것은 명령 위치가 예측 가능해야 한다는 점이다. 같은 종류의 명령이 화면마다 완전히 다른 위치에 있으면 사용자는 학습 비용을 치른다.

명령이 많아지면 overflow 메뉴가 필요하다. Overflow 안에 checked action이 있으면 trigger도 그 상태를 반영해야 한다. 그렇지 않으면 사용자는 현재 켜진 설정이 메뉴 안에 숨어 있는지 알 수 없다. 이런 세부 동작은 작아 보이지만 장시간 사용하는 도구의 신뢰에 영향을 준다.

I.5 히스토리와 복원

문서 히스토리는 실수를 복구하기 위한 안전망이다. 사용자는 과거 revision을 보고, 차이를 확인하고, 필요한 내용을 복사하거나 복원할 수 있어야 한다. 복원은 위험한 되돌리기가 아니라 명시적인 recovery flow로 설명하는 것이 좋다.

전체 매뉴얼에서는 히스토리를 두 층으로 나눠 설명할 수 있다. 하나는 현재 문서의 revision을 보는 문서 히스토리이고, 다른 하나는 바인더 전체에서 어느 문서가 언제 바뀌었는지 보는 바인더 히스토리다. 두 기능은 같은 기록 저장소를 공유할 수 있지만, 사용자의 질문은 다르다.

I.6 바인더 히스토리

바인더 히스토리는 “이 바인더에서 어떤 문서가 언제 바뀌었는가”에 답한다. 문서 하나의 diff보다, 시간대별 변경 흐름과 문서 row를 함께 보는 것이 중요하다. 삭제되었거나 rename된 문서도 과거 기록에는 남아 있을 수 있으므로, 현재 Shelf tree만 기준으로 하면 정보가 빠질 수 있다.

바인더 히스토리 문서는 matrix 개념을 설명할 수 있다. Row는 문서 또는 폴더, column은 시간 bucket, cell은 변경 신호다. 사용자가 cell을 클릭하면 관련 문서 히스토리로 들어갈 수 있다. 이 흐름은 탐색이지 복원 자체가 아니다.

I.7 Front matter

Front matter는 문서의 메타데이터를 담는다. 제목, 설명, 날짜, 상태, 태그, 배포 설정 같은 값이 들어갈 수 있다. 하지만 front matter가 본문보다 더 복잡해지면 초심자는 문서 작성을 어려워한다. 사용자 문서에서는 필요한 값과 자동으로 관리되는 값을 분리해서 설명해야 한다.

메타데이터 편집은 저장 안정성과 직접 연결된다. 본문과 front matter가 같은 문서 안에 있으므로, 어느 쪽을 고치든 저장 흐름이 안전해야 한다. 외부 도구가 custom field를 추가했을 때 Glif가 이를 보존하는지도 중요하다.

I.8 문서 상태와 분류

문서 상태는 팀이 문서를 운영하는 데 도움을 준다. 모든 문서가 상태를 가져야 하는 것은 아니지만, 기준 문서나 사용자 문서는 현재 상태가 분명해야 한다. draft, active, implemented, deprecated 같은 상태를 쓰면 문서를 읽는 사람이 신뢰도를 판단하기 쉽다.

상태는 장식이 아니라 행동을 이끈다. Draft 문서는 검토가 필요하고, active 문서는 변경 시 영향 범위를 확인해야 하며, deprecated 문서는 대체 문서를 연결해야 한다. 상태가 있어도 행동이 없다면 문서 운영에는 큰 도움이 되지 않는다.

I.9 테마와 시각 설정

테마는 작업 공간의 분위기와 읽기 피로도에 영향을 준다. 하지만 테마 설정은 구조 설정과 구분되어야 한다. 색, 배경, border, shadow 같은 visual field는 사용자가 조정할 수 있지만, layout mode나 overlay width처럼 구조에 영향을 주는 값은 더 엄격한 정책이 필요하다.

사용자 매뉴얼에서는 테마를 “글쓰기 표면을 조용하게 만드는 방법”으로 설명할 수 있다. 너무 많은 색을 조정하게 하기보다, 번들 테마를 선택하고 필요한 일부 항목만 다듬는 흐름이 좋다. 고급 theme JSON 편집은 별도 문서로 분리하는 편이 낫다.

I.10 리소스와 이미지 관리

문서에 이미지를 넣으면 본문과 리소스 파일의 관계가 생긴다. 이미지는 문서와 함께 이동하고 배포되어야 한다. 외부 URL 이미지를 그대로 참조할지, 바인더 리소스로 가져올지는 정책이 필요하다. 원격 이미지는 편하지만 나중에 사라질 수 있고, 로컬 리소스는 관리가 필요하다.

이미지 문서에서는 paste/drop, 파일 경로, remote size limit, 실패 상태를 설명한다. 사용자는 이미지가 보이지 않을 때 경로 문제인지, 권한 문제인지, 네트워크 문제인지 구분할 수 있어야 한다.

I.11 Export와 materialization

Export는 문서를 다른 형식으로 만드는 작업이다. PDF, Hugo publish, future static export는 모두 원문을 읽고 결과물을 만든다. Export는 editor preview와 같지 않다. Editor에서 보이는 preview가 곧 배포 결과로 확정된다는 뜻은 아니다.

Materialization 정책은 중요하다. 표 병합, 차트 참조, link render mode, embed 같은 projection 정보를 export에 어떻게 반영할지 정해야 한다. 일부 정보는 editor-only일 수 있고, 일부는 publish에 반영될 수 있다. 이 구분을 문서에 명확히 남겨야 한다.

I.12 접근성과 키보드

문서 편집 도구는 키보드로 충분히 사용할 수 있어야 한다. Slash Command, Block Inserter, table navigation, widget button, retry/reveal action은 keyboard focus와 activation key를 고려해야 한다. 마우스로만 가능한 기능은 장기적으로 사용성을 제한한다.

접근성 문서에서는 aria label, focus order, native control semantics를 설명할 수 있다. 사용자 문서에서는 모든 구현 세부사항을 말할 필요는 없지만, 키보드 사용자가 어떤 흐름으로 작업할 수 있는지는 알려야 한다.

I.13 오류 메시지와 진단

오류 메시지는 짧고 행동 가능해야 한다. “실패했습니다”만으로는 부족하고, “무엇을 다시 시도할 수 있는지”가 필요하다. 하지만 본문 안에 긴 stack trace나 내부 오류를 그대로 보여주면 사용자는 더 혼란스러워진다.

진단 정보는 별도 표면에 둘 수 있다. Context inspector, console log, support bundle 같은 경로가 있을 수 있다. 사용자 문서에서는 오류를 복구하기 위한 기본 순서를 제공하고, 내부 진단은 support 문서로 연결한다.

I.14 협업 전 준비

협업 기능이 없더라도 문서는 협업될 수 있다. 파일을 공유하고, Git으로 관리하고, export 결과를 전달하는 순간 여러 사람이 문서에 관여한다. 따라서 문서 이름, 상태, 변경 로그, 링크 구조는 협업 전에 준비되어야 한다.

협업 문서에서는 충돌 가능성을 설명해야 한다. 같은 문서를 여러 도구에서 동시에 고치면 외부 변경과 저장 충돌이 발생할 수 있다. 사용자는 충돌 상황에서 원문을 잃지 않는 방법을 알아야 한다.

I.15 release 전 문서 점검

Release 전에는 제품 기능뿐 아니라 문서도 점검한다. 사용자에게 보이는 문구가 현재 기능과 맞는지, partial 기능을 확정 기능처럼 설명하지 않았는지, 스크린샷이나 예시가 오래된 UI를 암시하지 않는지 확인한다.

문서 release checklist는 짧고 반복 가능해야 한다.

부록 J. 긴 문서 편집용 반복 구간

이 부록은 의도적으로 비슷한 구조의 섹션을 여러 개 둔다. 장문 에디터에서는 반복된 heading, 비슷한 표, 유사한 문단이 실제 문서에서도 자주 나타난다. 검색 결과, outline, active heading, fold, scroll restore가 이런 반복 구조를 혼동하지 않는지 확인할 수 있다.

J.1 반복 구간 01

이 구간은 짧은 설명, 표, 체크리스트가 이어지는 기본 패턴이다. 사용자는 운영 문서를 작성할 때 같은 패턴을 여러 번 반복한다. 에디터는 반복 구조에서도 현재 위치를 정확히 표시해야 한다.

• heading이 outline에 표시된다.
• 표가 정상적으로 렌더링된다.
• 체크리스트 marker가 본문 입력을 방해하지 않는다.

J.2 반복 구간 02

이 구간은 이전 구간과 비슷하지만 설명 문단을 조금 더 길게 둔다. 비슷한 heading과 유사한 본문이 이어질 때 검색 결과가 올바른 위치로 이동하는지 확인한다. 같은 단어가 반복되면 검색 highlight와 current selection이 겹칠 수 있으므로 시각적 우선순위도 확인한다.

• 검색 결과 이동이 정확하다.
• active heading이 현재 구간을 가리킨다.
• 저장 상태가 반복 입력 중 안정적이다.

J.3 반복 구간 03

이 구간은 링크가 포함된 반복 패턴이다. 작성 워크플로 샘플과 렌더러 점검 샘플 링크를 같은 문단 안에 둔다. 링크 hover와 graph indexing이 반복 링크를 어떻게 다루는지 확인한다.

• 링크 hover가 현재 링크와 맞는다.
• 링크 클릭 후 돌아오기가 예측 가능하다.
• 그래프에서 관계가 중복 과장되지 않는다.

J.4 반복 구간 04

이 구간은 코드 fence 근처의 반복 패턴이다. 코드 fence 안의 Markdown 문자가 실제 Markdown으로 렌더링되지 않는지 확인한다. 특히 링크나 heading marker가 코드 안에 있을 때 renderer가 이를 본문 구조로 착각하지 않아야 한다.

# 이 heading은 코드 안에 있다.
[이 링크도 코드 안에 있다](../somewhere/)
- [ ] 이 체크박스도 코드 안에 있다.

J.5 반복 구간 05

이 구간은 긴 문단 하나가 이어지는 패턴이다. 긴 문단은 line wrap, current line, selection, paragraph context를 확인하기 좋다. 문단 안에서 일부 텍스트를 선택하고, 선택을 해제하고, 중간에 단어를 삽입한다. 화면 폭이 바뀌어도 문단의 읽기 리듬이 과하게 흔들리지 않아야 한다.

긴 문단은 사용자가 실제로 전략 문서나 회고 문서를 작성할 때 자주 생긴다. 모든 문단을 짧게 나누라고 강제할 수는 없다. 따라서 에디터는 긴 문단에서도 안정적으로 작동해야 한다.

J.6 반복 구간 06

이 구간은 인용과 목록이 함께 있는 패턴이다.

반복되는 운영 원칙은 한곳에 기준을 두고, 다른 문서에서는 링크로 연결한다.

• 기준 문서는 변경 비용을 낮춘다.
• 샘플 문서는 회귀를 발견한다.
• Publish 문서는 현재 가능한 행동만 설명한다.

인용 marker와 목록 marker가 selection reveal과 충돌하지 않는지 확인한다. 긴 문서에서는 marker를 숨기는 기능이 많아질수록 source boundary를 잃기 쉽다.

J.7 반복 구간 07

이 구간은 표가 연속되는 패턴이다.

연속 표에서는 table parser가 인접 표를 혼동하지 않는지 확인한다. 표 사이의 빈 줄이 사라지면 하나의 큰 표처럼 해석될 수 있으므로, 편집 명령이 빈 줄을 안전하게 보존하는지 확인한다.

J.8 반복 구간 08

이 구간은 배포 문서에 가까운 안내 문체를 가진다. 사용자는 기능을 배우기 위해 문서를 읽고, 문서의 예시를 따라 한다. 따라서 문장 하나하나는 정확하고 검증 가능해야 한다. “곧 지원할 예정” 같은 표현은 publish 문서에서는 조심해야 한다.

문서 작성자는 독자의 행동을 먼저 생각한다. 이 장을 읽은 사용자가 다음에 무엇을 해야 하는지 분명하지 않다면, 문서를 더 쓰는 것이 아니라 구조를 다시 잡아야 한다.

J.9 반복 구간 09

이 구간은 troubleshooting 문체를 가진다.

문제가 재현되면 먼저 범위를 줄인다. 모든 문서에서 발생하는지, 특정 바인더에서만 발생하는지, 특정 renderer 근처에서만 발생하는지 확인한다. 범위가 줄어들면 원인을 찾기 쉬워진다.

재현 기록:
- 문서:
- 위치:
- 행동:
- 기대:
- 실제:

문제 해결 문서는 사용자가 안전하게 다음 행동을 선택하도록 돕는다. 실패를 숨기거나 자동으로 덮어쓰는 방식은 장기적으로 더 큰 문제를 만든다.

J.10 반복 구간 10

마지막 반복 구간은 문서 분리 기준을 다시 확인한다. 이 통합 문서는 장문 테스트에 필요하지만, 실제 사용자 매뉴얼은 이렇게 길면 안 된다. 분리 후에도 긴 샘플은 남겨 회귀 테스트에 사용한다.

분리할 때는 각 장의 링크를 다시 확인한다. 상대 링크는 파일 위치가 바뀌면 깨질 수 있다. 문서를 이동한 뒤에는 publish preview나 링크 검사를 실행해 사용자가 깨진 링크를 만나지 않도록 한다.

부록 K. 전체 매뉴얼 목차 후보

이 부록은 장문 샘플을 실제 문서 묶음으로 나눴을 때의 목차 후보다. 이 목차는 확정 정보가 아니라, 향후 문서 분리 작업의 출발점이다.

K.1 시작하기

• Glif의 문서 모델
• 첫 바인더 만들기
• 첫 문서 작성
• 저장 상태 확인
• 다시 열기

K.2 에디터

• Markdown 기본 작성
• Heading과 outline
• Slash Command
• Block Inserter
• 선택과 undo/redo
• 한국어 IME 입력

K.3 표

• 표 만들기
• 셀 이동
• 행과 열 편집
• 정렬과 열 너비
• 병합과 충돌 처리
• 차트 참조

K.4 링크와 그래프

• Markdown 링크
• Wiki 스타일 링크
• 링크 preview
• 깨진 링크 처리
• 지식 그래프
• _index.md 표시 정책

K.5 렌더러

• 이미지 preview
• 코드 블록
• 다이어그램
• 수식
• Callout
• Embed
• 실패와 원문 reveal

K.6 출력과 배포

• PDF 출력
• PDF 템플릿
• Publish 문서 작성
• Hugo 섹션 구조
• 배포 전 점검
• 링크와 리소스 검증

K.7 운영

• 문서 상태
• 변경 로그
• 히스토리
• 복원
• 문제 해결
• Release 전 문서 점검

K.8 내부 검증

• 장문 샘플 유지
• Dense 문서 세트
• Browser hot path probe
• Visual baseline
• Publish smoke
• PDF smoke

이 목차는 한 번에 모두 만들 필요가 없다. 가장 먼저 필요한 것은 시작하기, 에디터 기본, 문제 해결이다. 사용자가 처음 부딪히는 흐름과 막혔을 때의 복구 흐름이 안정되면, 고급 기능 문서를 더해도 전체 경험이 무너지지 않는다.

부록 L. 50k 장문 여유 구간

이 부록은 문서 길이를 50,000자 이상으로 안정적으로 유지하기 위한 여유 구간이다. 내용은 단순 filler가 아니라, 실제 장문 문서 품질을 볼 때 함께 확인해야 하는 운영 관찰 항목으로 구성한다. 나중에 문서를 분리하더라도 이 부록은 장문 회귀 샘플에 남겨 둘 수 있다.

L.1 긴 문서의 첫 인상

긴 문서를 처음 열었을 때 사용자가 느끼는 것은 기능 목록이 아니라 안정감이다. 본문이 먼저 보이고, 커서가 예측 가능한 곳에 있으며, 보조 패널이 늦게 갱신되더라도 화면이 흔들리지 않으면 사용자는 계속 작업할 수 있다. 반대로 첫 화면이 늦게 뜨거나, outline이 생기면서 본문이 밀리거나, 저장 상태가 불분명하면 문서 내용이 아무리 좋아도 에디터를 신뢰하기 어렵다.

이 관찰은 자동 테스트만으로 닫기 어렵다. 수치가 필요하지만, 수치만으로는 충분하지 않다. 사람이 실제로 문서를 열고, 잠시 기다리고, 스크롤하고, 중간에 입력해 보는 과정에서 화면의 안정감을 확인해야 한다. 장문 샘플은 이런 수동 관찰을 반복 가능하게 만드는 기준점이다.

L.2 긴 문서의 중간 진입

사용자는 긴 문서를 처음부터 읽지 않는다. 검색 결과, 링크, 그래프, outline을 통해 중간으로 들어온다. 따라서 중간 heading 아래의 문단은 독립적으로 이해될 수 있어야 한다. 이 문서의 각 장이 비슷한 설명을 조금씩 반복하는 이유도 중간 진입을 테스트하기 위해서다.

중간 진입 테스트에서는 검색으로 특정 단어를 찾고, 결과를 선택하고, 그 위치에서 바로 입력한다. 입력 후 undo를 수행하고, 다시 검색 결과를 이동한다. 이 과정에서 selection과 scroll이 예측 가능하게 유지되어야 한다. 검색 highlight, current line, active heading이 서로 충돌하지 않는지도 함께 본다.

L.3 긴 문서의 끝부분 편집

문서 끝부분 편집은 흔히 놓치는 시나리오다. 많은 기능이 문서 앞쪽이나 현재 viewport 근처에서는 잘 작동하지만, 문서 끝에서 append할 때 offset mapping이나 scroll restore 문제가 드러날 수 있다. 특히 긴 문서 끝에 표나 code fence가 있을 경우, 새 문단이 fence 안으로 들어가는지 밖으로 나오는지 사용자가 명확히 알 수 있어야 한다.

끝부분 편집 후 저장하고 다시 열어 보는 것도 중요하다. 마지막 위치 복원이 지원되지 않더라도, 문서가 끝까지 보존되고 outline이 깨지지 않아야 한다. 끝부분에 새 heading을 추가했을 때 그래프나 outline이 나중에 정상적으로 반영되는지도 확인한다.

L.4 긴 문서와 문서 분리

긴 문서는 테스트에는 좋지만 실제 사용자 매뉴얼로는 부담이 될 수 있다. 따라서 장문 샘플과 실제 매뉴얼은 목적을 나눠야 한다. 장문 샘플은 회귀와 성능을 보기 위한 문서이고, 실제 매뉴얼은 사용자의 질문별로 분리된 문서 묶음이어야 한다.

분리 과정에서 중요한 것은 링크와 용어의 일관성이다. 통합 문서 안에서는 같은 용어를 한 번 정의하고 뒤에서 반복할 수 있지만, 분리 후에는 각 문서가 자신의 독자에게 필요한 만큼 다시 설명해야 한다. 이때 중복 설명을 두려워하기보다, 기준 정의로 연결되는 링크를 적절히 사용하는 것이 좋다.

L.5 긴 문서와 성능 예산

성능 예산은 숫자만 적는다고 지켜지지 않는다. 어떤 작업이 hot path이고, 어떤 작업이 background로 밀려도 되는지 정해야 한다. 입력, selection, scroll, hover는 즉시 반응해야 한다. 전체 문서 분석, 그래프 갱신, publish 준비, PDF layout 계산은 사용자가 기다릴 수 있는 다른 단계로 분리할 수 있다.

장문 테스트에서는 작업별 예산을 따로 관찰한다. 문서를 여는 시간, 첫 입력까지의 시간, typing frame, save materialization, outline 갱신, renderer async completion, graph update, publish transform을 같은 하나의 “느림”으로 뭉개지 않는다. 느림의 위치를 알아야 올바른 곳을 고칠 수 있다.

L.6 긴 문서와 실패 복구

긴 문서에서 실패 복구는 더 중요하다. 사용자가 짧은 메모를 잃는 것도 문제지만, 긴 매뉴얼이나 회의 기록을 잃으면 신뢰가 크게 깨진다. 저장 실패, 렌더링 실패, 링크 실패, publish 실패는 서로 다른 실패다. 각각의 실패는 사용자에게 다른 다음 행동을 제공해야 한다.

좋은 실패 처리는 조용하지만 숨기지 않는다. 본문 입력을 막지 않고, 실패 위치를 좁히고, 다시 시도하거나 원문을 볼 수 있게 한다. 실패를 자동으로 덮어쓰거나, 사용자가 모르게 fallback 결과를 기준처럼 보여주는 방식은 피해야 한다.

L.7 긴 문서와 제품 문서 품질

제품 문서는 사용자가 제품을 배우는 경로다. 장문 문서가 테스트용이라고 해도, publish tree 안에 있다면 문장 품질을 유지해야 한다. 무작위 문자열이나 의미 없는 반복은 장기적으로 문서 저장소의 품질을 낮춘다. 테스트 문서도 실제 운영 문서처럼 읽을 수 있어야 한다.

이 문서는 의도적으로 전체 기능 매뉴얼의 초안처럼 작성되었다. 나중에 분리할 수 있는 장을 만들고, 현재 확정되지 않은 정책은 확정 기능처럼 말하지 않으며, 검증과 운영 관점의 설명을 함께 둔다. 장문 테스트와 문서 품질 테스트를 동시에 수행하기 위한 선택이다.

L.8 긴 문서와 다음 작업

이 샘플이 충분히 길어졌다면 다음 작업은 별도 dense 문서 세트를 만드는 것이다. 이 문서는 mixed long-form에 가깝다. 추가로 heading dense, table dense, renderer dense, link dense, IME dense 문서를 따로 만들면 병목을 더 잘 분리할 수 있다. 모든 성능 문제를 하나의 통합 문서에서 찾으려 하면 원인이 흐려진다.

다만 첫 단계에서는 이 통합 문서 하나만으로도 많은 회귀를 발견할 수 있다. 새 editor 변경이 들어간 뒤 이 문서를 열고, 중간에 입력하고, 링크를 hover하고, 표와 코드 블록 근처를 스크롤하고, publish 검사를 돌리면 기본 안정성을 빠르게 확인할 수 있다.

L.9 샘플 유지보수 메모

이 문서의 길이는 테스트 조건이므로, 문장을 다듬거나 장을 분리할 때 50,000자 아래로 내려가지 않았는지 다시 확인한다. 실제 매뉴얼로 분리한 뒤에도 장문 회귀용 사본은 남겨 두는 것이 좋다. 분리된 사용자 문서는 짧고 목적 중심이어야 하지만, 회귀 샘플은 일부러 길고 다양한 구조를 포함해야 한다. 두 문서의 목적을 섞지 않으면 사용자 문서 품질과 성능 테스트 품질을 동시에 유지할 수 있다.

샘플을 갱신할 때는 의미 없는 반복 문자를 추가하지 않는다. 새로운 기능이 생기면 관련 장에 실제 운영 문장으로 반영하고, 기능이 제거되면 해당 장을 오래됨 상태나 검증 노트로 바꾼다. 이렇게 관리하면 장문 테스트 문서가 단순한 부하 파일이 아니라, 제품 문서 체계를 점검하는 살아 있는 기준 문서가 된다.

마지막 확인 항목은 “이 문서를 실제 사람이 읽을 수 있는가”이다. 성능 테스트 문서라도 문장과 구조가 무너지면 장기적으로 버려진다. 유지되는 샘플은 제품 방향, 문서 정책, 에디터 안정성의 변화를 함께 담아야 한다. 그러면 긴 문서를 열어 보는 단순 smoke가 실제 사용 품질을 확인하는 작업으로 이어진다.

이 파일을 줄일 때는 먼저 실제 사용자 매뉴얼로 분리할 장을 옮기고, 장문 회귀에 필요한 구조만 남긴다. 길이를 줄인 뒤에는 문자 수, heading 수, 링크 수, code fence 수를 다시 기록한다. 이렇게 하면 샘플이 우연히 짧아져 장문 테스트 역할을 잃는 일을 막을 수 있다.

장문 기준은 항상 명시적으로 재측정한다.