feat: 문서 구조 변경 및 tech-visual 스킬 추가
This commit is contained in:
DongHyeonka
@@ -0,0 +1,114 @@
|
||||
# Studio 초안 검토
|
||||
|
||||
초안을 Studio에 넣고 **저장까지만** 한 뒤 미리보기로 읽는다. 게시하지 않는다.
|
||||
|
||||
파서를 통과한 본문도 화면에서는 다르게 보인다. 표가 가로로 넘치거나, 설명 없이 코드만 있거나,
|
||||
callout이 연달아 나와 읽는 흐름이 끊기는 것은 파서가 잡지 못한다.
|
||||
|
||||
## 왜 저장까지만인가
|
||||
|
||||
게시는 공개 사이트에 올린다. 되돌리려면 `unpublish`를 해야 하고 그 사이에 누구나 볼 수 있다.
|
||||
저장은 Studio 안에만 남는다 — 불완전한 초안도 저장할 수 있게 만들어진 이유가 이것이다.
|
||||
|
||||
`즉시 미리보기` 탭은 저장한 값이 아니라 **화면에 입력한 값**을 렌더링한다. 그래서 게시 없이도
|
||||
공개 화면과 같은 블록 렌더러로 본문을 볼 수 있다.
|
||||
|
||||
## 절차
|
||||
|
||||
1. `새 문서`에서 종류를 고르고 `작업본 만들기`
|
||||
2. 칸을 채운다. 본문은 미리 `check_body.mjs`를 통과시킨 것을 넣는다
|
||||
3. **`저장`** — `게시`가 아니다
|
||||
4. `즉시 미리보기` 탭으로 옮겨 아래 항목을 읽는다
|
||||
5. 고칠 것이 있으면 `편집` 탭으로 돌아가 고치고 다시 저장
|
||||
|
||||
Playwright로 할 때는 편집 화면의 `aside`에 버튼이 `저장`·`게시` 둘뿐이라는 점에 주의한다.
|
||||
**`게시`를 누르면 저장·검증·미리보기·게시가 한 번에 돈다.** 검토 단계에서는 `저장`만 누른다.
|
||||
|
||||
```js
|
||||
// 저장만 — aside 의 첫 버튼
|
||||
await page.locator('aside button').first().click();
|
||||
// 미리보기 탭
|
||||
await page.getByRole('tab', { name: '즉시 미리보기' }).click();
|
||||
```
|
||||
|
||||
## evidence를 넣었다면 화면을 새로 고친다
|
||||
|
||||
`즉시 미리보기`는 편집 화면이 들고 있는 asset 목록에서만 evidence 키를 찾는다. Asset을 방금
|
||||
올렸다면 그 목록에 아직 없어서 본문 전체가 이렇게 막힌다.
|
||||
|
||||
```text
|
||||
초안을 미리 볼 수 없습니다
|
||||
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 스냅샷에 옛 관계가 남아 있는 경우다.
|
||||
Reference in New Issue
Block a user