Studio 초안 검토

초안을 Studio에 넣고 저장까지만 한 뒤 미리보기로 읽는다. 게시하지 않는다.

파서를 통과한 본문도 화면에서는 다르게 보인다. 표가 가로로 넘치거나, 설명 없이 코드만 있거나, callout이 연달아 나와 읽는 흐름이 끊기는 것은 파서가 잡지 못한다.

왜 저장까지만인가

게시는 공개 사이트에 올린다. 되돌리려면 unpublish를 해야 하고 그 사이에 누구나 볼 수 있다. 저장은 Studio 안에만 남는다 — 불완전한 초안도 저장할 수 있게 만들어진 이유가 이것이다.

즉시 미리보기 탭은 저장한 값이 아니라 화면에 입력한 값을 렌더링한다. 그래서 게시 없이도 공개 화면과 같은 블록 렌더러로 본문을 볼 수 있다.

절차

새 문서에서 종류를 고르고 작업본 만들기
칸을 채운다. 본문은 미리 check_body.mjs를 통과시킨 것을 넣는다
저장 — 게시가 아니다
즉시 미리보기 탭으로 옮겨 아래 항목을 읽는다
고칠 것이 있으면 편집 탭으로 돌아가 고치고 다시 저장

Playwright로 할 때는 편집 화면의 aside에 버튼이 저장·게시 둘뿐이라는 점에 주의한다. 게시를 누르면 저장·검증·미리보기·게시가 한 번에 돈다. 검토 단계에서는 저장만 누른다.

// 저장만 — aside 의 첫 버튼
await page.locator('aside button').first().click();
// 미리보기 탭
await page.getByRole('tab', { name: '즉시 미리보기' }).click();

evidence를 넣었다면 화면을 새로 고친다

즉시 미리보기는 편집 화면이 들고 있는 asset 목록에서만 evidence 키를 찾는다. Asset을 방금 올렸다면 그 목록에 아직 없어서 본문 전체가 이렇게 막힌다.

초안을 미리 볼 수 없습니다
1:1 supported local evidence key not found: <asset-key>

Asset 업로드 패널로 올렸으면 화면이 바로 알지만, 다른 경로로 올렸다면 편집 화면을 한 번 새로 고쳐야 목록을 다시 받는다. 본문 문법 문제로 오해하기 쉽다.

미리보기에서 읽을 것

읽는 흐름

제목만 훑어도 무슨 이야기인지 따라가는가
첫 문단이 무엇을 다루는지 말하는가. 배경부터 길게 시작하지 않는가
문단이 너무 길어 화면에서 덩어리로 보이지 않는가
같은 말을 다른 자리에서 반복하지 않는가

본문 밖 칸

Case의 문제·결론·검증 환경·재현 조건도 본문이 아니라 평문이다. 백틱과 파이프가 글자 그대로 보인다.

백틱이 화면에 그대로 나오지 않는가
절차를 한 문단에 이어 쓰지 않았는가. 줄바꿈은 <br> 로 살아난다
한 칸이 화면에서 덩어리로 보이지 않는가
나열을 쉼표로 잇지 않았는가. 이름 : 값으로 줄을 나눴는가
한 문장이 화면에서 두 줄을 넘지 않는가

설명이 빠진 곳

표 바로 앞이나 뒤에 그 표를 어떻게 읽는지 적었는가
코드블록에 무엇을 보라는 설명이 있는가. 붙여 놓기만 하지 않았는가
처음 나오는 약어와 고유명사를 풀었는가. 왜 있는지까지 말했는가
이름만 대고 다음 문단으로 넘어간 자리가 없는가
두 값이 합쳐지는 곳에 합쳐진 결과가 있는가
직접 본 것과 테스트 계약이 구분돼 있는가
수치에 단위와 측정 조건이 붙었는가
그림의 alt와 caption이 무엇이 보이는지 말하는가

화면에서만 드러나는 것

표 머리글만 읽어도 그 표가 무엇을 묻는지 아는가
열을 더 줄일 수 있는가. 3열이 2열로 되는가
비교 표의 열 이름이 어느 시점·상태의 값인지 말하는가
표가 가로로 넘치지 않는가. 열이 너무 많지 않은가
코드블록이 가로 스크롤을 만들지 않는가. 긴 줄을 줄일 수 있는가
callout이 연달아 나와 본문 흐름을 끊지 않는가
제목 단계가 건너뛰지 않는가 (## 다음에 바로 ####)
그림이 의도한 자리에 있는가. 글과 섞여 사라지지 않았는가
그림 안에 문장이 없는가. <text>가 전부 이름인가

종류별

Case — 문제·결론·검증 환경·재현 조건 네 칸이 본문 없이도 이해되는가
Reference — 규칙 제목만 읽어도 무엇을 금지하는지 아는가
Question — 사실과 가정이 화면에서 구분돼 보이는가
Decision — 결정문이 한 문장인가. 영향에 감수한 비용이 있는가

고칠 것이 없을 때

references/review-checklist.md를 마지막으로 훑고 게시한다. 게시 뒤에는 공개 페이지를 열어 미리보기와 같게 보이는지 다시 확인한다 — 공개 경로는 미리보기와 다른 데이터를 쓴다.

초안을 남기지 않는다

검토용으로 만든 작업본은 지운다. Decision은 계약에 삭제 경로가 없으므로 확인용으로 만들지 않는 편이 낫다.

한 번이라도 게시한 문서는 게시를 취소해도 지워지지 않는다. 게시를 취소해 publicationStatus 가 UNPUBLISHED 가 된 뒤에도 삭제는 409 로 거절되고, 화면에는 「공개된 기록은 삭제할 수 없습니다. 먼저 공개를 취소해 주세요」가 뜬다. 이미 취소했는데도 그렇다. 그러므로 시험 삼아 게시하지 않는다. 게시 동작을 확인해야 하면 지워도 되는 문서를 따로 만들고, 그것이 목록에 영구히 남는다는 것을 감수한다.

관계로 참조된 문서도 지워지지 않는다(DOCUMENT_IN_USE). 참조하는 쪽의 관계를 먼저 끊는다. 끊어도 막히면 그 문서들의 지난 Public Preview 스냅샷에 옛 관계가 남아 있는 경우다.

6.0 KiB Raw Blame History