feat: 문서 구조 변경 및 tech-visual 스킬 추가
This commit is contained in:
DongHyeonka
@@ -0,0 +1,188 @@
|
||||
# 코드·표·다이어그램·이미지
|
||||
|
||||
본문(`bodyMarkdown`)에만 해당한다. 본문이 있는 종류는 Case 와 Concept 이다.
|
||||
|
||||
## 코드블록
|
||||
|
||||
````text
|
||||
```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` 하나만 쓴다. 다른 속성은 거절된다.
|
||||
|
||||
````text
|
||||
```sql label="N+1이 발생하는 조회"
|
||||
SELECT * FROM highlights WHERE feed_item_id = ?;
|
||||
```
|
||||
````
|
||||
|
||||
**코드에 자격증명·토큰·내부 호스트를 남기지 않는다.** 지울 때는 지웠다는 사실이 보이게 한다 —
|
||||
`Authorization: Bearer <생략>`처럼. 조용히 빼면 다음 사람이 그 헤더가 없었다고 읽는다.
|
||||
|
||||
붙여넣은 코드는 원문 그대로 둔다. 줄바꿈과 들여쓰기를 손보면 재현이 달라진다.
|
||||
|
||||
## 표
|
||||
|
||||
파이프로 그냥 쓴다. **감싸지 않는다.**
|
||||
|
||||
```text
|
||||
| N | 초기화 컬렉션 | 총 쿼리 |
|
||||
|---|---|---|
|
||||
| 10 | 10 | 25 |
|
||||
| 100 | 100 | 222 |
|
||||
| 1,000 | 1,000 | 2,022 |
|
||||
```
|
||||
|
||||
설명이나 행 머리글이 필요할 때만 `:::table`로 감싼다. 세 속성이 전부 있어야 한다.
|
||||
|
||||
```text
|
||||
:::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열로 줄일 수 있으면 줄이고, 첫 열
|
||||
문구를 짧게 해서 값 열을 왼쪽으로 당긴다.
|
||||
|
||||
```text
|
||||
3열 2열로
|
||||
| 방어선 | 무엇을 막나 | 뚫리면 | → | 위치 | 여기서 어떻게 막지? |
|
||||
```
|
||||
|
||||
세 번째 열에 있던 내용은 표 다음 문단에서 이어 쓴다.
|
||||
|
||||
## 다이어그램·SVG
|
||||
|
||||
### 그림에 문장을 넣지 않는다
|
||||
|
||||
가장 흔한 실패다. 설명을 그림 안으로 밀어 넣으면 라벨이 길어지고, 글자는 작아지고, 검색도
|
||||
복사도 화면 낭독도 안 되는 텍스트가 된다. 그림은 **관계**를 보이고 문장은 그 옆 문단에 쓴다.
|
||||
|
||||
지킬 선:
|
||||
|
||||
| 항목 | 기준 |
|
||||
|---|---|
|
||||
| 상자 | 7개 이하. 넘으면 그림을 나눈다 |
|
||||
| 라벨 | 한 줄 40자 이하. 문장이 아니라 이름 |
|
||||
| 글자 크기 | 2종 (제목·보조). 3종부터는 위계가 아니라 소음이다 |
|
||||
| 색 | 의미를 색에만 싣지 않는다. 빗금·테두리·위치를 함께 쓴다 |
|
||||
| 화살표 | 방향이 논지일 때만. 장식으로 긋지 않는다 |
|
||||
| 숫자 | 넣지 않는다. 산문에 쓴다 |
|
||||
|
||||
빨강·초록 조합은 피한다. 색각 이상에서 구분되지 않는다.
|
||||
|
||||
**자가 점검.** 올리기 전에 `<text>`를 전부 뽑아 읽는다.
|
||||
|
||||
```bash
|
||||
grep -o '<text[^>]*>[^<]*</text>' 그림.svg
|
||||
```
|
||||
|
||||
하나라도 아래에 걸리면 문장이므로 뺀다. 길이가 아니라 **서술하느냐**가 기준이다 — 40자 이하여도
|
||||
문장은 문장이다.
|
||||
|
||||
- 마침표나 물음표로 끝난다
|
||||
- 서술어가 있다 — `~있다`, `~막는다`, `~바꿔도`
|
||||
- 조사로 두 대상을 잇는다 — `A를 B로`, `A에서 B까지`
|
||||
|
||||
`세 가지가 한 영역 안에 있다`는 그림이 이미 보여 주는 것을 글로 다시 쓴 것이다. 상자를 한
|
||||
영역 안에 그렸으면 그 문장은 필요 없다. 지우면 그림이 더 명확해진다.
|
||||
|
||||
`<title>`과 `<desc>`는 예외다. 화면을 못 보는 사람이 듣는 자리이므로 여기에는 문장을 쓴다.
|
||||
그림 안에서 뺀 설명이 갈 곳이기도 하다.
|
||||
|
||||
### 무엇을 그릴지 정하는 법
|
||||
|
||||
그림 하나에 주장 하나다. "이 그림이 없으면 독자가 무엇을 못 보나"에 한 문장으로 답할 수
|
||||
없으면 그리지 않는다. 표로 되는 것을 그림으로 그리지 않는다 — 표는 값을 비교하고, 그림은
|
||||
**포함·순서·경계**처럼 자리로만 보이는 것을 맡는다.
|
||||
|
||||
Studio는 다이어그램을 그려 주지 않는다. **파일로 만들어 Asset으로 올린다.**
|
||||
|
||||
1. `본문에 Asset 삽입` → `업로드 종류`를 **다이어그램**으로 → `Asset 업로드`
|
||||
2. 목록에서 고르면 커서 자리에 `:::evidence` 구문이 삽입된다
|
||||
|
||||
SVG는 `image/svg+xml`로 올라가고 다른 이미지와 같게 다뤄진다. 벡터라 확대해도 깨지지 않으니
|
||||
구조도·흐름도에 맞다.
|
||||
|
||||
올리기 전에 SVG에서 지울 것:
|
||||
|
||||
- `<script>` 요소와 `on*` 속성
|
||||
- 외부 폰트·이미지 참조 — 열람자 환경에서 안 불러온다. 글자는 path로 변환하거나 일반 폰트만
|
||||
- 절대 좌표에 의존하는 고정 크기 — `viewBox`를 두어 늘어나게 한다
|
||||
|
||||
## 증거 이미지
|
||||
|
||||
```text
|
||||
:::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으로 쓴다.
|
||||
|
||||
```text
|
||||
|
||||
```
|
||||
|
||||
**문단 하나가 그림 하나로만 이루어져야** 그림으로 인식된다. 글과 섞으면 인라인 이미지가 되어
|
||||
거절된다.
|
||||
|
||||
설명이 필요하면 Markdown title을 쓰지 말고 — 거절된다 — `:::evidence`의 `caption`을 쓰거나
|
||||
그림 다음 문단에 쓴다.
|
||||
|
||||
## 무엇을 어디에 쓰나
|
||||
|
||||
| 담을 것 | 쓸 것 |
|
||||
|---|---|
|
||||
| 명령어·설정·소스 | 코드블록 |
|
||||
| 숫자 비교 | 표 |
|
||||
| 구조·흐름 | SVG 다이어그램 Asset |
|
||||
| 화면·로그 캡처 | 이미지 Asset + `zoom="true"` |
|
||||
| 놓치면 안 되는 단서 | `:::warning` |
|
||||
| 곁가지 설명 | `:::note` |
|
||||
|
||||
캡처로 표를 대신하지 않는다. 그림 속 숫자는 검색도 복사도 안 되고 화면 낭독기가 읽지 못한다.
|
||||
Reference in New Issue
Block a user