diff --git a/components/DoDont/DoDont.module.css b/components/DoDont/DoDont.module.css index bf3f781..33ee73b 100644 --- a/components/DoDont/DoDont.module.css +++ b/components/DoDont/DoDont.module.css @@ -1,15 +1,27 @@ .container { display: grid; - grid-template-columns: repeat(2, 1fr); + grid-template-columns: 1fr; gap: 1rem; } +@media (min-width: 768px) { + .container { + grid-template-columns: repeat(2, 1fr); + } +} + .directive { border-style: solid; border-width: 1px; border-radius: 0.375rem; padding: 1rem; margin-bottom: 1rem; + overflow: hidden; +} + +.directive pre { + overflow-x: auto; + max-width: 100%; } .directiveTitle { diff --git a/docs/sentence/concreteness.mdx b/docs/sentence/concreteness.mdx index 5da9bd1..31c61d5 100644 --- a/docs/sentence/concreteness.mdx +++ b/docs/sentence/concreteness.mdx @@ -116,7 +116,7 @@ Internet Explorer에서는 정상적으로 동작하지 않습니다. -### ✅ 실제 동작을 이해할 수 있게 쓰세요 +### ✅ 업계의 관용 표현을 구체적인 동작으로 풀어쓰세요 기술 문서를 읽으면 코드나 시스템이 실제로 무엇을 하는지 바로 이해할 수 있어야 해요. 업계에서만 통하는 표현은 실제 동작을 명확하게 설명하지 못해서 문장의 뜻을 흐려요. 독자가 의미를 혼동하지 않도록 문서에서는 실제 동작을 분명하게 드러내는 표현을 사용해 주세요. @@ -222,6 +222,7 @@ Windows 7과 같은 구형 운영체제에서는 소프트웨어를 설치해도 **4. 의미를 명확하게 바꿔보세요.** > 클라이언트가 서버를 찔러서 응답을 확인합니다. + ::: details 정답 확인 클라이언트가 서버에 요청을 보내서 응답을 확인합니다. ::: diff --git a/docs/visualization/callout.mdx b/docs/visualization/callout.mdx new file mode 100644 index 0000000..c425718 --- /dev/null +++ b/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 반드시 백업 후 데이터베이스를 마이그레이션하세요 +마이그레이션 과정에서 스키마가 변경되면 기존 데이터가 손실될 수 있어요. +::: + +### ✅ 독자에게 꼭 전달하고 싶은 내용을 제목으로 쓰세요 + +콜아웃은 제목과 본문으로 나뉘어요. 제목은 콜아웃의 첫 줄에 위치하고 굵은 글씨로 표시돼서 독자가 가장 먼저 확인해요. +따라서 제목에 전달하려는 내용을 작성하면 독자가 어떤 내용인지 바로 파악할 수 있어서 콜아웃의 효과를 높일 수 있어요. + + + +::: warning 인증 토큰 관련 +토큰이 만료되면 다시 로그인해야 해요. +::: +- 제목만 읽으면 독자가 어떤 행동을 해야 하는지 알기 어려워요. + + +::: warning 인증 토큰이 만료되었는지 확인하세요. +토큰이 만료된 상태에서 요청하면 서버가 401 에러를 반환해요. +::: +- 제목만 읽어도 어떤 상황을 말하는지, 왜 중요한지 바로 이해할 수 있어요. + + + + +::: info 콜아웃의 제목에는 마침표를 붙이지 않아요 +일반적으로 모든 종류의 제목에는 마침표를 붙이지 않아요. 따라서 콜아웃의 제목에도 마침표를 붙이지 않아요. +마침표는 문장의 끝을 나타내는데, 제목 끝에 마침표가 있으면 내용이 끝난 것처럼 느껴져 시각적으로 답답해 보이고 자연스럽지 않기 때문이에요. +::: + +## 실습 문제 + +아래 문장을 보고 콜아웃을 어떻게 구성할지 생각해 본 뒤, 정답과 비교해 보세요. + +### 1. 콜아웃으로 구성하면 좋은 내용을 찾아 보세요 + +> 이 설정을 활성화하면 모든 API 요청이 로그로 남습니다. +> 하지만 트래픽이 많은 환경에서는 로그 용량이 빠르게 증가할 수 있기 때문에 배포 환경에서는 꼭 필요한 경우에만 사용하는 것이 좋습니다. + +::: details 정답 확인 + +다음 문장을 콜아웃으로 강조할 수 있어요. + +> 하지만 트래픽이 많은 환경에서는 로그 용량이 빠르게 증가할 수 있기 때문에 배포 환경에서는 꼭 필요한 경우에만 사용하는 것이 좋습니다. + +기능을 잘못 사용하면 문제가 생길 수 있다고 경고하는 내용이기 때문에 WARNING 콜아웃으로 구성하면 좋아요. 예를 들어 다음과 같이 작성할 수 있어요. + +``` +::: warning 배포 환경에서는 꼭 필요한 경우에만 사용하세요 +모든 API 요청이 로그로 남아서, 트래픽이 많은 환경에서는 로그 용량이 빠르게 증가할 수 있어요. +::: +``` + +::: + +### 2. 다음 내용을 콜아웃으로 바꿀 때 제목과 본문으로 구분해 보세요 + +> 데이터 마이그레이션을 실행하기 전에 기존 데이터를 백업해야 합니다. +> 마이그레이션 중 스키마가 변경되면 일부 데이터가 손실될 수 있습니다. + +::: details 정답 확인 +``` +::: danger 마이그레이션 전에 반드시 데이터를 백업해야 합니다 +스키마가 변경되면 기존 데이터가 손실될 수 있습니다. +::: +``` + +제목에는 독자에게 꼭 전달해야 하는 정보를, 본문에는 그 이유를 간단히 설명해요. + +::: \ No newline at end of file diff --git a/docs/visualization/index.md b/docs/visualization/index.md new file mode 100644 index 0000000..5eaef74 --- /dev/null +++ b/docs/visualization/index.md @@ -0,0 +1,28 @@ +--- +head: + - - meta + - property: og:title + content: 시각적으로 구분하기 +--- + +# 시각적으로 구분하기 + +기술 문서는 글로만 구성되지 않아요. 독자에게 내용을 효과적으로 전달하기 위해서는 다양한 시각 요소를 활용하면 좋아요. 시각 요소를 적절하게 사용하면 중요한 내용이 자연스럽게 드러나고, 글로 설명하기 어려운 내용을 보완해서 독자가 내용을 더 쉽게 이해할 수 있어요. + +기술 문서에서 주로 사용하는 시각 요소는 다음과 같아요. + +- **콜아웃**: 중요한 정보나 주의해야 할 내용을 시각적으로 강조해요. +- **목록**: 항목을 간단하게 나열해서 내용을 빠르게 스캔할 수 있어요. 절차가 있으면 글 목록를 쓰고, 순서와 상관없으면 점 목록을 써요. +- **표**: 여러 항목을 비교하거나 구조화된 정보를 깔끔하게 정리해요. +- **코드 블록**: 예시 코드를 보기 좋게 보여주고 그대로 복사할 수 있어요. 사용 방법이나 설정 예시를 안내할 때 사용해요. +- **인라인 코드**: 문장 안에서 함수 이름이나 변수 같은 코드 요소를 구분해서 보여줘요. + +### [콜아웃으로 강조하기](./callout.mdx) + +- 콜아웃 사용 목적에 따라 색상을 구분하세요. +- 독자에게 꼭 전달하고 싶은 내용을 제목으로 쓰세요. + +### [목록으로 정리하기](./list.mdx) + +- 흐름이 있는 설명에는 목록을 사용하지 마세요. +- 핵심만 짧게 전달할 수 있을 때 사용해요. \ No newline at end of file diff --git a/docs/visualization/list.mdx b/docs/visualization/list.mdx new file mode 100644 index 0000000..29fa0ca --- /dev/null +++ b/docs/visualization/list.mdx @@ -0,0 +1,166 @@ +--- +head: + - - meta + - property: og:title + content: 목록으로 정리하기 +--- + +import { DoDont } from '@/components/DoDont/DoDont'; + +# 목록으로 정리하기 + +목록은 여러 항목을 정리해서 보여 주는 시각 요소예요. 정보를 나열하거나 독자가 빠르게 핵심을 파악해야 할 때 도움이 돼요. + +목록은 크게 두 가지를 사용할 수 있어요. 전달하려는 정보의 성격에 맞는 목록을 사용하면 독자가 내용을 더 쉽게 파악할 수 있어요. + +- 점 목록: 순서가 중요하지 않은 항목을 나열할 때 사용해요. 예를 들어 특징, 조건, 장점처럼 항목을 나열하는 순서가 바뀌어도 의미가 달라지지 않을 때 사용해요. +- 번호 목록: 순서가 중요한 내용을 나열할 때 사용해요. 단계별 절차나 따라해야 할 순서가 있는 설명일 때 적합해요. + +::: info 문장에는 마침표를 붙이세요 + +AI로 작성된 문서에서는 목록을 문장이 아니라 정보 항목이나 요약 단위로 처리하는 경향이 있어서 문장 끝의 마침표가 생략되는 경우가 많아요. +하지만 한국어에서는 목록 안에 있더라도 문장이라면 마침표를 쓰는 편이 더 자연스러워요. + +::: + +## 체크 리스트 + +### ✅ 문장에 순서나 인과관계가 있으면 목록을 사용하지 않아요 + +목록을 사용하면 정보를 빠르게 훑어볼 수 있어요. 기능이나 옵션을 나열할 때처럼 항목 사이에 순서나 인과관계가 없는 경우에 특히 잘 어울려요. + +앞의 설명이 뒤의 설명을 뒷받침하거나, 원인과 결과처럼 논리가 이어진다면 문장으로 이어서 쓰는 게 좋아요. +이런 내용을 목록으로 나열하면 문장 간 논리 구조가 잘 드러나지 않아서 독자가 흐름을 다시 파악해야 해요. + + + + +- 이 모듈은 비동기 방식으로 데이터를 처리합니다. +- 데이터 처리 속도가 이전 버전보다 20% 향상되었습니다. +- 사용자는 더 빠른 응답 시간을 경험할 수 있습니다. +--- +각 항목이 독립적인 정보를 전달하는 것처럼 보이지만, 실제로는 하나의 흐름을 가진 설명이에요. +하나의 흐름을 가진 정보가 목록으로 나뉘어서 글의 순서와 인과관계가 잘 드러나지 않아요. + + + +이 모듈은 데이터를 비동기 방식으로 처리하기 때문에 이전 버전보다 처리 속도가 20% 향상되었습니다. 결과적으로 사용자는 훨씬 빠른 응답 시간을 경험할 수 있습니다. + +--- +설명이 문장으로 자연스럽게 이어져서 새로운 엔진이 사용자 경험을 어떻게 개선하는지 한 흐름으로 전달해요. 독자가 전체 과정을 자연스럽게 이해할 수 있어요. + + + + +### ✅ 핵심만 짧게 전달할 수 있을 때 사용해요 + +각 항목을 한두 문장으로 써도 의미가 충분히 전달될 때 목록을 사용해요. 반대로 하나의 항목에 설명이 계속 붙으면 읽어야 할 양이 늘어나고, 중요한 내용이 눈에 잘 들어오지 않아요. + +이럴 때는 목록 대신 heading을 사용하는 게 좋아요. +핵심을 드러내는 제목으로 내용을 나누고, 각 항목을 문장으로 풀어 설명하면 정보 구조가 더 분명해지고 가독성도 높아져요. + + + +``` +캐시의 특징은 다음과 같아요. +- 응답 속도 개선: 캐시는 서버에서 계산하거나 조회한 결과를 임시로 저장해요. 같은 요청이 반복되면 서버에 다시 요청하지 않고 캐시된 데이터를 사용해요. 이 과정에서 네트워크 비용과 처리 시간이 줄어들어요. 트래픽이 많은 서비스에서는 성능에 큰 영향을 줘요. +- 서버 부하 감소: 캐시를 사용하면 서버가 동일한 작업을 반복해서 처리하지 않아도 돼요. 데이터베이스 조회 횟수가 줄어들고, 서버 리소스를 더 효율적으로 사용할 수 있어요. 특히 읽기 요청이 많은 환경에서 효과가 커요. +- 저장 위치에 따른 특성: 캐시는 메모리나 디스크에 저장할 수 있어요. 메모리 캐시는 빠르지만 용량이 제한적이고, 디스크 캐시는 용량은 크지만 상대적으로 느려요. 서비스 특성에 따라 적절한 방식을 선택해야 해요. +- 데이터 정합성 문제: 캐시된 데이터가 실제 데이터와 달라질 수 있어요. 캐시 만료 정책을 잘못 설정하면 오래된 데이터를 반환할 수 있어요. 그래서 캐시를 사용할 때는 데이터 갱신 전략을 함께 고려해야 해요. +``` +각 항목에 들어간 정보량이 많은데도 목록으로 나열했어요. 이렇게 하면 독자는 항목을 훑어보는 대신, 긴 설명을 하나씩 따라 읽어야 해요. + + +``` +## 캐시의 특징 + +### 응답 속도 개선 +캐시는 서버에서 계산하거나 조회한 결과를 임시로 저장해요. 같은 요청이 반복되면 서버에 다시 요청하지 않고 캐시된 데이터를 사용해요. 이로 인해 네트워크 비용과 처리 시간이 줄어들고, 전체 응답 속도가 빨라져요. + +### 서버 부하 감소 +캐시를 사용하면 서버가 동일한 작업을 반복해서 처리하지 않아도 돼요. 데이터베이스 조회 횟수가 줄어들고, 서버 리소스를 더 효율적으로 사용할 수 있어요. + +### 저장 위치에 따른 특성 +캐시는 메모리나 디스크에 저장할 수 있어요. 메모리 캐시는 빠르지만 용량이 제한적이고, 디스크 캐시는 용량은 크지만 상대적으로 느려요. 서비스 특성에 맞는 방식을 선택해야 해요. + +### 데이터 정합성 문제 +캐시는 실제 데이터와 차이가 날 수 있어요. 캐시 만료 정책이 적절하지 않으면 오래된 데이터를 반환할 수 있어서, 데이터 갱신 전략을 함께 설계해야 해요. +``` +특징을 heading으로 분리했어요. 설명이 길어도 제목을 기준으로 내용을 나눠서 읽을 수 있기 때문에 각 특징을 쉽게 이해할 수 있어요. + + + +::: warning heading으로 나누다 보면 문서가 복잡해질 수 있어요. + +목록 대신 heading을 사용했을 때 `####`(H4) 이하로 내려간다면 한 문서에서 너무 많은 내용을 다루고 있다는 신호일 수 있어요. 이럴 때 하나의 문서에서 다루는 주제가 여러 개라면 문서를 나누는 편이 나을 수 있어요. + +자세한 내용은 [한 페이지에서는 하나만 다루기](https://technical-writing.dev/architecture/one-thing-per-one-page.html#-%EC%A0%9C%EB%AA%A9-%EA%B9%8A%EC%9D%B4%EA%B0%80-h4-%EC%9D%B4%EC%83%81%EC%9D%B4-%EB%90%98%EB%A9%B4-%EB%AC%B8%EC%84%9C%EB%A5%BC-%EB%82%98%EB%88%84%EB%8A%94-%EA%B2%83%EC%9D%84-%EA%B3%A0%EB%A0%A4%ED%95%98%EC%84%B8%EC%9A%94) 문서를 참고하세요. + +::: + +## 실습 문제 + +아래 문장을 보고 목록을 어떻게 구성할지 생각해본 뒤, 정답과 비교해 보세요. + +### 1. 목록을 사용할지, 다른 방식으로 작성할지 판단해 보세요 + +> 실험적 기능을 사용할 때 주의할 점은 다음과 같아요. +> +> - 향후 버전에서 동작이 변경될 수 있어요. +> - 예고 없이 제거될 수 있어요. +> - 운영 환경에서는 사용을 권장하지 않아요. + +::: details 정답 확인 + +**목록을 사용해요.** + +문장이 하나의 흐름으로 연관되어 있지 않아서 목록을 사용하면 좋아요. + +::: + +> HTTP 요청을 처리하는 과정은 다음과 같아요. +> +> - 클라이언트가 요청을 전송해요. +> - 서버는 요청 헤더와 바디를 파싱해요. +> - 인증 정보가 없으면 요청을 거부해요. +> - 인증에 실패하면 401 상태 코드를 반환해요. +> - 인증에 성공하면 비즈니스 로직을 실행해요. + +::: details 정답 확인 + +**문장으로 이어 써요.** + +이 내용은 요청 수신 → 파싱 → 인증 → 처리로 이어지는 하나의 흐름이에요. 이런 설명을 목록으로 나열하면 독자가 내용 간 흐름을 다시 파악해야 해서, 문장으로 이어 쓰는 편이 이해하기 쉬워요. + +예를 들어 다음과 같이 작성할 수 있어요. +``` +HTTP 요청은 클라이언트가 서버로 요청을 전송하면서 시작해요. 서버는 요청을 받으면 먼저 헤더와 바디를 파싱해서 요청 내용을 확인해요. 이 과정에서 인증 정보를 검사하고, 인증 정보가 없거나 유효하지 않으면 요청을 거부해요. +인증에 실패한 경우 서버는 401 상태 코드를 반환해요. 인증이 성공하면 그다음 단계로 비즈니스 로직을 실행해요. +``` + +::: + +> 로그 레벨의 종류는 다음과 같아요. +> +> - `ERROR`: 시스템에서 더 이상 처리할 수 없는 문제가 발생했을 때 기록해요. 서비스 운영에 직접적인 영향을 주기 때문에 즉시 확인하고 조치해야 해요. +> +> - `WARN`: 당장은 문제가 없지만, 이후 오류로 이어질 수 있는 상황을 기록해요. 반복해서 발생한다면 원인을 분석하는 게 좋아요. + +::: details 정답 확인 + +**heading으로 나눠서 작성해요.** + +각 항목의 내용이 너무 길어요. 이런 경우에는 heading을 사용해서 설명하는 편이 더 이해하기 쉬워요. + +예를 들어 다음과 같이 작성할 수 있어요. +``` +## 로그 레벨의 종류 + +### `ERROR` +시스템에서 더 이상 처리할 수 없는 문제가 발생했을 때 기록해요. 서비스 운영에 직접적인 영향을 주기 때문에 즉시 확인하고 조치해야 해요. + +### `WARN` +당장은 문제가 없지만, 이후 오류로 이어질 수 있는 상황을 기록해요. 반복해서 발생한다면 원인을 분석하는 게 좋아요. +``` + +::: \ No newline at end of file diff --git a/rspress.config.ts b/rspress.config.ts index 9e84bd6..d344b5b 100644 --- a/rspress.config.ts +++ b/rspress.config.ts @@ -166,6 +166,24 @@ export default defineConfig({ }, ], }, + { + text: 'Step 4. 시각적으로 구분하기', + collapsed: true, + items: [ + { + text: '소개', + link: '/visualization/index', + }, + { + text: '콜아웃으로 강조하기', + link: '/visualization/callout', + }, + { + text: '목록으로 정리하기', + link: '/visualization/list', + }, + ], + }, ], }, },