내용에 맞는 시각 표현 고르기

결론부터

• 비교는 표, 절차는 단계, 관계는 그림, 시간에 따른 상태 변화는 상호작용으로 보여 주면 이해하기 쉽다.
• AI에게는 도구 이름보다 독자가 무엇을 구별하거나 관찰해야 하는지 전달한다.
• 기존 표현으로 학습 질문을 해결하기 어려울 때 새 컴포넌트를 요청한다.

이 장에서 처음 나오는 말1개

컴포넌트Component

탭·카드·단계 선택기처럼 여러 문서에서 재사용하는 화면 요소.

같은 내용도 긴 문단으로 읽을 때와 차이를 나란히 볼 때 이해 속도가 다르다. 이 사이트의 컴포넌트는 반복해서 쓰는 화면 요소다. 아래 실물을 보며 필요한 표현을 고르면 된다. 구현 문법을 외울 필요는 없다.

보여 주려는 내용에서 고른다

보여 줄 것	맞는 표현	요청할 때 쓸 말
같은 항목의 차이	표	두 방식의 입력·결과·쓰는 조건을 같은 행에서 비교해줘
순서대로 해야 하는 일	단계 목록·Steps	각 단계에 할 일과 끝났음을 확인할 결과를 보여줘
독자마다 하나만 필요한 갈래	탭·Tabs	환경을 고르면 그 환경의 설명을 읽게 해줘
큰 분류와 역할	카드·CardGrid	각 역할의 차이를 짧게 훑을 수 있게 해줘
제품의 실제 위치·모양	이미지	화면에서 어느 부분을 봐야 하는지 표시해줘
개념의 경계·연결·방향	D2 다이어그램	구성 요소 사이의 관계와 화살표 의미를 보여줘
단계별 메시지·보관 상태	LearningFlow	한 단계씩 이동하며 누가 무엇을 갖는지 보여줘

Steps·Tabs·CardGrid는 Starlight가 제공하는 컴포넌트이고, LearningFlow는 이 저장소에서 만든 학습용 컴포넌트다. D2 그림은 별도 통합이 생성한다. AI는 이미 있는 요소를 먼저 활용하고, 설명에 필요한 부분을 맞춰 넣는다.

절차는 완료 조건과 함께 보여 준다

다음은 수정된 문서를 확인하는 순서를 Steps로 표현한 예다. 순서만 눈에 띄는 것이 아니라 각 단계에서 무엇을 해야 하는지 읽을 수 있어야 한다.

1. 수정된 절을 읽는다. 처음 질문했던 내용에 답이 생겼는지 본다.

2. 예제를 따라간다. 입력이나 단계를 바꿨을 때의 결과를 설명해 본다.

3. 남은 의문을 요청한다. 페이지 URL과 막힌 부분을 함께 보내 다음 수정을 맡긴다.

순서가 없는 특징 목록이라면 일반 목록이 더 간단하다.

탭은 자기에게 필요한 갈래를 고르게 한다

다음 두 탭은 문서를 다시 찾는 상황의 예다. 지금 상황에 맞는 쪽을 선택해 본다.

문서 제목을 안다

덱 사이드바에서 해당 페이지를 연다. 페이지 안의 특정 설명을 찾을 때는 페이지 목차에서 절로 이동한다.

증상이나 용어만 기억한다

헤더의 전역 검색에 그 말을 입력한다. 예를 들어 보관 상태로 검색해 관련 설명을 찾고, 필요한 절의 링크를 남긴다.

두 방식의 차이를 동시에 비교해야 한다면 표가 낫다. 모두 알아야 할 전제나 주의사항을 탭 뒤에 숨기지 않는다.

카드는 큰 역할을 구별하게 한다

관계를 한눈에

다이어그램은 구성 요소와 연결을 펼쳐 놓는다. 전체 구조에서 지금 보는 부분을 찾는 데 쓴다.

변화를 한 단계씩

학습 컴포넌트는 현재 단계에 집중하게 한다. 값이 오가고 상태가 달라지는 이유를 따라가는 데 쓴다.

카드만 읽어도 두 역할의 차이를 말할 수 있는지 본다. 자세한 조건과 근거는 카드 아래 본문에서 설명한다.

강조 상자는 본문의 중요한 조건을 드러낸다

그림을 읽을 지점을 먼저 알려 준다

“아래 그림을 보자”보다 “서버에서 브라우저로 향하는 화살표와 응답 뒤 남는 값을 보자”가 독자가 어디에 집중해야 하는지 알려 준다.

결론 상자와 용어 상자도 같은 목적이다. 핵심은 첫머리에 드러내고, 낯선 말은 필요한 자리에서 풀어 준다. 모든 문단을 상자로 감싸면 중요도를 구별하기 어려우므로 설명의 흐름은 본문에 남긴다.

실제 모습을 알아야 하면 이미지를 쓴다

화면 명칭 안내는 이 사이트의 실제 화면에 이름표를 붙인 예다. 글로 위치를 길게 설명하는 대신 이미지와 같은 이름으로 대상을 가리킬 수 있다.

제품을 설명할 때도 공식 문서의 화면·구조도를 우선 확인한다. 이미지 아래에는 “가운데 요청 목록에서 실패한 항목을 보자”처럼 이번 질문에 필요한 지점을 안내하고, 원문 출처를 함께 남긴다. 이 사이트는 외부 이미지를 저장소에 보관하고 SourceFigure로 출처와 설명을 표시한다.

이 페이지의 관리 화면 설명에 공식 문서의 이미지를 넣어줘. 독자가 선택해야 하는 영역과 선택 후 달라지는 부분을 안내하고, 출처와 대체 텍스트를 남겨줘.

실제 UI를 알려 주는 자리에는 존재하지 않는 화면을 그려 넣지 않는다. 설명용 개념 그림이라면 실제 제품 화면과 구별해서 소개한다.

새 컴포넌트는 관찰할 변화를 정해 요청한다

기존 그림이나 표로 답하기 어려운 질문이면 새 표현을 만들 수 있다. 다음은 아직 구현된 기능을 소개하는 것이 아니라 새 학습 예제를 요청하는 예시다.

캐시 문서에서 TTL을 바꾸면 같은 시간 간격의 요청들이 언제 캐시에 적중하는지 보고 싶어. 시간 간격과 TTL을 조절하고 결과를 비교할 수 있는 작은 예제를 만들어줘. 계산 가정과 관찰할 결과를 본문에 설명하고, 조작하지 않아도 기본 사례를 읽을 수 있게 해줘.

AI가 구현한 뒤에는 “움직인다”에서 멈추지 않고 값을 바꿨을 때 왜 결과가 달라지는지 설명해 본다. 모바일·키보드에서도 조작할 수 있는지는 새 동작에 맞춰 AI가 검증하게 한다. 구현 지침은 저장소의 콘텐츠 작성 규칙에 있다.

D2로 정적 다이어그램 그리기D2 그림을 읽고 요청하며, Mermaid 대신 선택한 이유를 살펴본다.