"시각적으로 구분하기" 섹션 생성, 문서 개선

docs/sentence/concreteness.mdx

@@ -116,7 +116,7 @@ Internet Explorer에서는 정상적으로 동작하지 않습니다.
 </DoDont.Do>
 </DoDont>
 
-### ✅ 실제 동작을 이해할 수 있게 쓰세요
+### ✅ 업계의 관용 표현을 구체적인 동작으로 풀어쓰세요
 
 기술 문서를 읽으면 코드나 시스템이 실제로 무엇을 하는지 바로 이해할 수 있어야 해요. 업계에서만 통하는 표현은 실제 동작을 명확하게 설명하지 못해서 문장의 뜻을 흐려요. 독자가 의미를 혼동하지 않도록 문서에서는 실제 동작을 분명하게 드러내는 표현을 사용해 주세요.
 
@@ -222,6 +222,7 @@ Windows 7과 같은 구형 운영체제에서는 소프트웨어를 설치해도
 **4. 의미를 명확하게 바꿔보세요.**
 
 > 클라이언트가 서버를 찔러서 응답을 확인합니다.
+
 ::: details 정답 확인
 클라이언트가 서버에 요청을 보내서 응답을 확인합니다.
 :::

docs/visualization/callout.mdx

@@ -0,0 +1,128 @@
+---
+head:
+  - - meta
+    - property: og:title
+      content: 콜아웃으로 강조하기
+---
+
+# 콜아웃으로 강조하기
+
+import { DoDont } from '@/components/DoDont/DoDont';
+
+콜아웃은 독자의 시선을 강하게 끌어서 본문 안에 섞여 있으면 지나칠 수 있는 정보를 쉽게 인지하게 해요. 그래서 놓치기 쉬운 중요한 내용을 전달할 때 특히 효과적이에요.
+문서 전체에서 강조해야 하는 정보나 주의해야 하는 사항을 시각적으로 구분해서 독자가 자연스럽게 읽게 하려면 콜아웃을 사용하세요.
+
+## 체크리스트
+
+### ✅ 콜아웃 사용 목적에 따라 종류를 구분하세요
+
+콜아웃은 **전달하려는 정보의 성격과 중요도**에 따라 구분해서 사용해요. 종류를 나누면 독자는 지금 읽는 내용이 참고용인지, 꼭 따라야 할 지침인지 바로 판단할 수 있어요.
+일반적으로 콜아웃은 다음 네 가지로 구분해요.
+
+**1. INFO**
+
+부가 정보를 전달할 때 사용해요. 참고 문서나 배경 지식처럼 본문을 이해하는 데 도움이 되는 내용을 덧붙일 때 적합해요.
+예를 들어 React 프로젝트 설치 방법을 설명하는 문서에서는 npm과 Yarn의 차이를 설명하는 콜아웃을 추가해서 패키지 매니저를 선택하는 데 필요한 배경 지식을 제공할 수 있어요.
+
+::: info npm과 Yarn의 차이
+
+npm은 Node.js를 설치하면 함께 제공되기 때문에 별도 설정 없이 바로 시작하고 싶을 때 사용하기 좋아요. 간단한 프로젝트나 기본적인 패키지 관리가 필요할 때 적합해요. 
+
+Yarn은 의존성 설치 속도와 재현성을 중점으로 개선한 도구예요. 팀 단위로 작업하거나, 패키지 버전을 엄격하게 맞춰야 하는 프로젝트에서 사용하기 좋아요.
+
+더 자세한 내용은 [npm 공식 문서](https://docs.npmjs.com/about-npm)와 [Yarn 공식 문서](https://yarnpkg.com/getting-started/usage)를 참고하세요.
+
+:::
+
+**2. TIP**
+
+권장 사항이나 모범 사례를 안내할 때 사용해요. 다음 예시처럼 성능 향상을 위해 자주 조회되는 데이터를 캐싱하도록 권장할 수 있어요.
+
+::: tip 자주 조회하는 데이터는 캐싱을 권장해요
+자주 조회하는 데이터를 캐싱하면 서버 요청 횟수를 줄일 수 있어요. 이렇게 하면 응답 시간이 짧아지고 서버 부하도 함께 줄어들어요.
+:::
+
+**3. WARNING**
+
+당장 치명적인 문제는 아니지만, 잘못 사용하면 잠재적인 위험이 생길 수 있는 정보를 전달할 때 사용해요.
+다음 예시는 특정 기능을 무분별하게 사용했을 때 성능 저하로 이어질 수 있음을 미리 알리는 경우예요.
+
+::: warning 이 기능은 꼭 필요한 경우에만 적용하세요
+불필요한 중복 요청은 서버 부하를 증가시키고 응답 속도를 느리게 만들어요.
+:::
+
+**4. DANGER**
+
+확인하지 않으면 즉각적인 문제나 장애로 이어질 수 있는 위험도가 높은 정보를 전달할 때 사용해요.
+다음 예시는 사전 조치를 하지 않으면 데이터 손실이 바로 발생할 수 있는 상황을 경고해요.
+
+::: danger 반드시 백업 후 데이터베이스를 마이그레이션하세요
+마이그레이션 과정에서 스키마가 변경되면 기존 데이터가 손실될 수 있어요.
+:::
+
+### ✅ 독자에게 꼭 전달하고 싶은 내용을 제목으로 쓰세요
+
+콜아웃은 제목과 본문으로 나뉘어요. 제목은 콜아웃의 첫 줄에 위치하고 굵은 글씨로 표시돼서 독자가 가장 먼저 확인해요. 
+따라서 제목에 전달하려는 내용을 작성하면 독자가 어떤 내용인지 바로 파악할 수 있어서 콜아웃의 효과를 높일 수 있어요.
+
+<DoDont>
+<DoDont.Dont>
+::: warning 인증 토큰 관련
+토큰이 만료되면 다시 로그인해야 해요.
+:::
+- 제목만 읽으면 독자가 어떤 행동을 해야 하는지 알기 어려워요.
+</DoDont.Dont>
+<DoDont.Do>
+::: warning 인증 토큰이 만료되었는지 확인하세요.
+토큰이 만료된 상태에서 요청하면 서버가 401 에러를 반환해요.
+::: 
+- 제목만 읽어도 어떤 상황을 말하는지, 왜 중요한지 바로 이해할 수 있어요.
+</DoDont.Do>
+</DoDont>
+
+
+::: info 콜아웃의 제목에는 마침표를 붙이지 않아요
+일반적으로 모든 종류의 제목에는 마침표를 붙이지 않아요. 따라서 콜아웃의 제목에도 마침표를 붙이지 않아요.  
+마침표는 문장의 끝을 나타내는데, 제목 끝에 마침표가 있으면 내용이 끝난 것처럼 느껴져 시각적으로 답답해 보이고 자연스럽지 않기 때문이에요.
+:::
+
+## 실습 문제
+
+아래 문장을 보고 콜아웃을 어떻게 구성할지 생각해 본 뒤, 정답과 비교해 보세요.
+
+### 1. 콜아웃으로 구성하면 좋은 내용을 찾아 보세요
+
+> 이 설정을 활성화하면 모든 API 요청이 로그로 남습니다.  
+> 하지만 트래픽이 많은 환경에서는 로그 용량이 빠르게 증가할 수 있기 때문에 배포 환경에서는 꼭 필요한 경우에만 사용하는 것이 좋습니다.
+
+::: details 정답 확인
+
+다음 문장을 콜아웃으로 강조할 수 있어요.
+
+> 하지만 트래픽이 많은 환경에서는 로그 용량이 빠르게 증가할 수 있기 때문에 배포 환경에서는 꼭 필요한 경우에만 사용하는 것이 좋습니다.
+
+기능을 잘못 사용하면 문제가 생길 수 있다고 경고하는 내용이기 때문에 WARNING 콜아웃으로 구성하면 좋아요. 예를 들어 다음과 같이 작성할 수 있어요.
+
+```
+::: warning 배포 환경에서는 꼭 필요한 경우에만 사용하세요
+모든 API 요청이 로그로 남아서, 트래픽이 많은 환경에서는 로그 용량이 빠르게 증가할 수 있어요.
+:::
+```
+
+:::
+
+### 2. 다음 내용을 콜아웃으로 바꿀 때 제목과 본문으로 구분해 보세요
+
+> 데이터 마이그레이션을 실행하기 전에 기존 데이터를 백업해야 합니다.  
+> 마이그레이션 중 스키마가 변경되면 일부 데이터가 손실될 수 있습니다.
+
+::: details 정답 확인
+```
+::: danger 마이그레이션 전에 반드시 데이터를 백업해야 합니다
+스키마가 변경되면 기존 데이터가 손실될 수 있습니다.
+:::
+```
+
+제목에는 독자에게 꼭 전달해야 하는 정보를, 본문에는 그 이유를 간단히 설명해요.
+
+:::

docs/visualization/index.md

@@ -0,0 +1,23 @@
+---
+head:
+  - - meta
+    - property: og:title
+      content: 시각적으로 구분하기
+---
+
+# 시각적으로 구분하기
+
+기술 문서는 글로만 구성되지 않아요. 독자에게 내용을 효과적으로 전달하기 위해서는 다양한 시각 요소를 활용하면 좋아요. 시각 요소를 적절하게 사용하면 중요한 내용이 자연스럽게 드러나고, 글로 설명하기 어려운 내용을 보완해서 독자가 내용을 더 쉽게 이해할 수 있어요.
+
+기술 문서에서 주로 사용하는 시각 요소는 다음과 같아요.
+
+- **콜아웃**: 중요한 정보나 주의해야 할 내용을 시각적으로 강조해요.
+- **리스트**: 항목을 간단하게 나열해서 내용을 빠르게 스캔할 수 있어요. 절차가 있으면 번호를 쓰고, 순서와 상관없으면 글머리 기호를 써요.
+- **표**: 여러 항목을 비교하거나 구조화된 정보를 깔끔하게 정리해요.
+- **코드 블록**: 예시 코드를 보기 좋게 보여주고 그대로 복사할 수 있어요. 사용 방법이나 설정 예시를 안내할 때 사용해요.
+- **인라인 코드**: 문장 안에서 함수 이름이나 변수 같은 코드 요소를 구분해서 보여줘요.
+
+### [콜아웃으로 강조하기](./callout.mdx)
+
+- 콜아웃 사용 목적에 따라 색상을 구분하세요.
+- 독자에게 꼭 전달하고 싶은 내용을 제목으로 쓰세요

rspress.config.ts

@@ -166,6 +166,20 @@ export default defineConfig({
             },
           ],
         },
+        {
+          text: 'Step 4. 시각적으로 구분하기',
+          collapsed: true,
+          items: [
+            {
+              text: '소개',
+              link: '/visualization/index',
+            },
+            {
+              text: '콜아웃으로 강조하기',
+              link: '/visualization/callout',
+            },
+          ],
+        },
       ],
     },
   },