4.9 KiB
기록 .md 의 어디가 Studio 의 어느 칸인가
세 자리
기록 .md |
Studio |
|---|---|
| frontmatter | 메타데이터. 화면 칸이 아니다 |
| 제목 바로 아래 첫 문단 | 요약 칸 |
## <이름> |
같은 이름의 칸 |
## 요약 이라는 절을 만들지 않는다 — Studio 에 그런 칸이 없어 통째로 사라진다. ## 출처 도
칸이 아니다. 원본 경로는 frontmatter 의 source 에 있다.
종류마다의 칸
| 종류 | 기록 .md 의 ## 이름 |
본문 |
|---|---|---|
| Case | 관계 · 문제 · 결론 · 검증 환경 · 재현 조건 · 본문 |
있음 |
| Concept | 관계 · 본문 |
있음 |
| Reference | 관계 · 목적 · 규칙 · 적용 조건 · 예외 · 예시 |
없음 |
| Question | 관계 · 사실 · 가정 · 미지수 · 제약 · 선택지 · 다음 검증 |
없음 |
| Decision | 근거 · 결정문 · 판단 이유 · 영향 |
없음 |
Decision 만 관계 절 이름이 근거 다. 그리고 근거가 1개 이상 없으면 게시가 거절된다.
화면의 라벨은 기록의 절 이름과 다르다
이것이 이 문서에서 가장 자주 틀리는 자리다. 위 표는 기록 .md 가 쓰는 이름이고,
편집 화면의 라벨은 다른 말을 쓴다. 그리고 /studio/documents/new 의 종류 카드에 적힌 요약
(목적 · 규칙 · 적용 조건 · 예외 · 예시)은 카드 문구이지 편집 화면의 라벨이 아니다.
Reference 에서 실제로 확인한 대응이다.
기록의 ## |
편집 화면의 라벨 |
|---|---|
목적 |
이 기준을 쓰는 이유 |
규칙 |
판단 기준 — 제목과 본문 두 칸이 한 줄이다 |
적용 조건 |
적용할 때 |
예외 |
예외와 주의 |
예시 |
예시 |
관계 |
관계 |
종류 이름도 자리마다 다르다. 상태 레일은 Reference 를 적용 기준 이라고 부르고,
새 문서 화면의 라디오는 Reference 다.
화면을 먼저 스냅샷으로 읽고 그 라벨을 쓴다. 이 표를 외워서 넣지 않는다 — 화면이 바뀌면 표가 먼저 낡는다.
기록에 없는데 화면에 있는 칸
| 칸 | 무엇 |
|---|---|
축 |
주제 안의 변이(SPA · Mediator · BFF · Forward-Auth). 주제를 고른 뒤에 나타난다. 안 고르면 주제 공통 기록이 된다 |
마지막 검증일 |
기록의 verifiedOn 이다. 없으면 비워 둔다 |
근거가 없으면 비워 둔다. verifiedOn 이 없는 채로 저장하면 미리보기에 「마지막 검증」 절이
값 없이 뜬다. 그것은 날짜를 지어내는 것보다 낫다 — 게시 전에 사람이 채울지 정한다.
frontmatter 에서 화면으로 가는 값
| frontmatter | 어디로 |
|---|---|
id |
편집 주소 /studio/documents/<id>/edit |
kind |
새 문서를 만들 때 고르는 종류 |
slug · title |
화면 위쪽의 슬러그·제목 칸 |
topic · topicName · project |
주제·프로젝트 선택 |
basisVersion (Concept) |
기준 버전 칸 |
questionStatus (Question) · decisionStatus (Decision) |
상태 선택 |
assets[].file |
올릴 Asset 파일 |
assets[].key |
본문 :::evidence key 의 저장소 쪽 이름. 올리면 서버 키로 바뀐다 |
계약이 화면에 주는 상태와 도메인이 들고 있는 상태가 다르다. QuestionStatus 는 화면에서
OPEN·RESOLVED 둘인데 도메인은 OPEN·INVESTIGATING·PAUSED·RESOLVED 넷이고,
Decision 의 도메인 ACCEPTED 가 화면에서는 ADOPTED 로 보인다. 화면에서 고른 값이 도메인
상태를 덮어쓰지는 않는다.
본문이 없는 세 종류
Reference·Question·Decision 의 칸은 평문으로 렌더링된다.
- 백틱과 파이프가 글자 그대로 보인다. 코드·표를 넣지 않는다
- 줄바꿈은
<br>로만 살아난다 - 나열은 쉼표로 잇지 말고
이름 : 값으로 줄을 나눈다
코드·표·그림이 필요하면 짝이 되는 Case 나 Concept 에 담고 관계 로 가리킨다.
본문을 넣기 전에
저장소의 .md 는 그림을 마크다운 이미지로 싣는다. Studio 는 :::evidence 를 쓴다. 바꾸는 것은
스크립트가 한다.
python3 scripts/studio-body.py <기록.md> --body-only # 저장소 key 그대로
python3 scripts/studio-body.py <기록.md> --key a=a-1a2b3c4d --body-only # 서버가 준 key 로
저장소 파일 자체는 고치지 않는다.
되돌아오는 값
저장이 끝나면 Studio 가 id 를 준다. 새로 만든 기록이면 frontmatter 의 id 와 studio: 를
채운다. 그 두 칸이 차면 색인이 publication 을 게시됨 으로 적는데, 그것은 「Studio 에
있다」는 뜻이고 공개됐다는 뜻이 아니다. 공개 여부는 status 와 public: 이 말한다.