7.4 KiB
코드·표·다이어그램·이미지
본문(bodyMarkdown)에만 해당한다. 본문이 있는 종류는 Case 와 Concept 이다.
코드블록
```java
@Query("select fi from FeedItem fi join fetch fi.user")
List<FeedItem> findFeed(Pageable pageable);
```
언어는 ^[A-Za-z0-9][A-Za-z0-9_.+-]*$만 쓴다 — java, kotlin, sql, yaml, bash,
text. 언어를 모르면 text.
설명을 붙이려면 label 하나만 쓴다. 다른 속성은 거절된다.
```sql label="N+1이 발생하는 조회"
SELECT * FROM highlights WHERE feed_item_id = ?;
```
코드에 자격증명·토큰·내부 호스트를 남기지 않는다. 지울 때는 지웠다는 사실이 보이게 한다 —
Authorization: Bearer <생략>처럼. 조용히 빼면 다음 사람이 그 헤더가 없었다고 읽는다.
붙여넣은 코드는 원문 그대로 둔다. 줄바꿈과 들여쓰기를 손보면 재현이 달라진다.
표
파이프로 그냥 쓴다. 감싸지 않는다.
| N | 초기화 컬렉션 | 총 쿼리 |
|---|---|---|
| 10 | 10 | 25 |
| 100 | 100 | 222 |
| 1,000 | 1,000 | 2,022 |
설명이나 행 머리글이 필요할 때만 :::table로 감싼다. 세 속성이 전부 있어야 한다.
:::table id="direct-measurement" caption="N별 직접 측정값" rowHeaderColumn="1"
| N | 초기화 컬렉션 | 총 쿼리 |
|---|---|---|
| 10 | 10 | 25 |
:::
id— 문서 안에서 유일해야 한다. 제목 id와도 겹치면 안 된다rowHeaderColumn—"1"이면 첫 열이 행 머리글, 아니면"none"- 정렬은 구분줄로 준다:
|---:|오른쪽,|:---:|가운데
측정값과 파생값을 한 표에 섞지 않는다. 섞어야 한다면 성격 열을 두어 어느 것이 잰 값이고 어느 것이 계산한 값인지 밝힌다.
머리글이 질문이면 행이 답이 된다
열 이름을 명사로 두면 독자가 표를 훑는다. 질문으로 두면 읽고 답을 얻는다.
| 쓰지 않는다 | 쓴다 |
|---|---|
memory-only가 줄이는가 |
memory-only가 위험을 막아주나..? |
남는 데이터 · reload 뒤 |
reload 전 · reload 후 |
확인함 · 확인 안 함 |
o · x |
비교 표의 축은 시점이나 상태로 못 박는다. 전·후, 켬·끔처럼 어느 때의 값인지 열
이름이 말해야 한다. 남는 데이터 같은 두루뭉술한 이름을 쓰면 그 열이 언제 얘긴지 본문을 다시
봐야 한다.
있음·없음을 가르는 열은 o·x로 채운다. 열이 좁아지고 값이 눈에 띄게 갈린다. 문장 안이 아니라
값 자리에서만 쓴다.
열을 줄인다. 감싸개가 --body-copy(672px)에 묶여 있고 표에는 min-width: 780px이 걸려
있어서, 열이 몇 개든 오른쪽 108px은 늘 잘린다. 3열을 2열로 줄일 수 있으면 줄이고, 첫 열
문구를 짧게 해서 값 열을 왼쪽으로 당긴다.
3열 2열로
| 방어선 | 무엇을 막나 | 뚫리면 | → | 위치 | 여기서 어떻게 막지? |
세 번째 열에 있던 내용은 표 다음 문단에서 이어 쓴다.
다이어그램·SVG
그림에 문장을 넣지 않는다
가장 흔한 실패다. 설명을 그림 안으로 밀어 넣으면 라벨이 길어지고, 글자는 작아지고, 검색도 복사도 화면 낭독도 안 되는 텍스트가 된다. 그림은 관계를 보이고 문장은 그 옆 문단에 쓴다.
지킬 선:
| 항목 | 기준 |
|---|---|
| 상자 | 7개 이하. 넘으면 그림을 나눈다 |
| 라벨 | 한 줄 40자 이하. 문장이 아니라 이름 |
| 글자 크기 | 2종 (제목·보조). 3종부터는 위계가 아니라 소음이다 |
| 색 | 의미를 색에만 싣지 않는다. 빗금·테두리·위치를 함께 쓴다 |
| 화살표 | 방향이 논지일 때만. 장식으로 긋지 않는다 |
| 숫자 | 넣지 않는다. 산문에 쓴다 |
빨강·초록 조합은 피한다. 색각 이상에서 구분되지 않는다.
자가 점검. 올리기 전에 <text>를 전부 뽑아 읽는다.
grep -o '<text[^>]*>[^<]*</text>' 그림.svg
하나라도 아래에 걸리면 문장이므로 뺀다. 길이가 아니라 서술하느냐가 기준이다 — 40자 이하여도 문장은 문장이다.
- 마침표나 물음표로 끝난다
- 서술어가 있다 —
~있다,~막는다,~바꿔도 - 조사로 두 대상을 잇는다 —
A를 B로,A에서 B까지
세 가지가 한 영역 안에 있다는 그림이 이미 보여 주는 것을 글로 다시 쓴 것이다. 상자를 한
영역 안에 그렸으면 그 문장은 필요 없다. 지우면 그림이 더 명확해진다.
<title>과 <desc>는 예외다. 화면을 못 보는 사람이 듣는 자리이므로 여기에는 문장을 쓴다.
그림 안에서 뺀 설명이 갈 곳이기도 하다.
무엇을 그릴지 정하는 법
그림 하나에 주장 하나다. "이 그림이 없으면 독자가 무엇을 못 보나"에 한 문장으로 답할 수 없으면 그리지 않는다. 표로 되는 것을 그림으로 그리지 않는다 — 표는 값을 비교하고, 그림은 포함·순서·경계처럼 자리로만 보이는 것을 맡는다.
Studio는 다이어그램을 그려 주지 않는다. 파일로 만들어 Asset으로 올린다.
본문에 Asset 삽입→업로드 종류를 다이어그램으로 →Asset 업로드- 목록에서 고르면 커서 자리에
:::evidence구문이 삽입된다
SVG는 image/svg+xml로 올라가고 다른 이미지와 같게 다뤄진다. 벡터라 확대해도 깨지지 않으니
구조도·흐름도에 맞다.
올리기 전에 SVG에서 지울 것:
<script>요소와on*속성- 외부 폰트·이미지 참조 — 열람자 환경에서 안 불러온다. 글자는 path로 변환하거나 일반 폰트만
- 절대 좌표에 의존하는 고정 크기 —
viewBox를 두어 늘어나게 한다
증거 이미지
:::evidence key="asset-key" alt="무엇을 보여 주는 그림인가" caption="설명" zoom="true"
:::
- 네 속성이 전부 있어야 한다. 본문은 비운다
key는^[a-z0-9]+(?:-[a-z0-9]+)*$zoom="true"면 눌러서 확대할 수 있다. 표·로그처럼 글자가 작으면 켠다alt는 화면을 못 보는 사람이 읽는 문장이다. "스크린샷"이 아니라 무엇이 보이는지 쓴다- 장식용 그림은 Asset의
decorative를 켜고alt를 비운다
READY가 아닌 Asset은 게시 시 거절된다.
일반 이미지
Asset이 아닌 그림은 Markdown으로 쓴다.
문단 하나가 그림 하나로만 이루어져야 그림으로 인식된다. 글과 섞으면 인라인 이미지가 되어 거절된다.
설명이 필요하면 Markdown title을 쓰지 말고 — 거절된다 — :::evidence의 caption을 쓰거나
그림 다음 문단에 쓴다.
무엇을 어디에 쓰나
| 담을 것 | 쓸 것 |
|---|---|
| 명령어·설정·소스 | 코드블록 |
| 숫자 비교 | 표 |
| 구조·흐름 | SVG 다이어그램 Asset |
| 화면·로그 캡처 | 이미지 Asset + zoom="true" |
| 놓치면 안 되는 단서 | :::warning |
| 곁가지 설명 | :::note |
캡처로 표를 대신하지 않는다. 그림 속 숫자는 검색도 복사도 안 되고 화면 낭독기가 읽지 못한다.