한 페이지에서는 하나의 목표만 다루세요
문서를 작성할 때 한 페이지에서 하나의 핵심 목표만 다루는 것이 중요해요. 한 문서에서 너무 많은 내용을 담으면 독자가 핵심을 파악하기 어려워지고, 필요한 정보를 빠르게 찾기 어려워질 수 있어요.
1. 가독성이 높아지고 탐색이 쉬워요
문서가 너무 길어지거나 한 페이지에 여러 개념이 뒤섞이면 독자가 원하는 정보를 찾기가 어려워요. 각 문서가 하나의 주제에 집중한다면, 독자는 원하는 정보를 더 빠르고 쉽게 탐색할 수 있어요.
2. 문서 유지보수가 쉬워요
하나의 문서에서 너무 많은 내용을 다루면 추후 업데이트가 어려워질 수 있어요. 특정 개념이 변경될 때 관련 내용을 찾아 수정하는 것이 어려워지고, 중복된 내용이 여러 문서에서 발생할 수도 있어요.
3. 구조가 복잡해지는 것을 막아요
제목의 위계가 4단계(####, H4) 이상으로 깊어진다면, 그 문서는 여러 개의 문서로 나누어야 할 신호예요. 문서의 계층 구조가 너무 복잡해지면, 독자가 문서의 흐름을 이해하기 어려워지고 정보를 빠르게 스캔하기가 어려워져요.
체크리스트
✅ 제목 깊이가#### (H4) 이상이 되면 문서를 나누는 것을 고려하세요
### (H3)까지는 유지할 수 있지만, #### (H4)부터는 문서가 지나치게 깊어졌다는 신호예요. 이럴 때는 하위 개념을 별도의 문서로 분리하는 것이 가독성과 탐색성을 높여보세요.
Don't
이 문서는 "React 사용법"라는 너무 넓은 주제를 다루고 있어요. 한 페이지에서 너무 많은 개념을 한꺼번에 설명하면, 독자가 원하는 정보를 찾기가 어려워져요. H4(####), H5(#####)와 같은 깊은 제목이 등장하면 문서를 분리해야 할 신호예요.
Do
이 페이지에서는 'React 컴포넌트 생성'이라는 하나의 목표만 다루고 있어요. 컴포넌트 생성과 관련된 주요 내용을 다루지만, 개별적인 개념을 한 페이지에서 지나치게 세부적으로 파고들지는 않아요.
✅ 개요를 다루는 페이지를 활용해 보세요
여러 개념을 개략적으로 소개해야 한다면, 개별 문서로 연결되는 개요 페이지를 따로 만드는 것이 좋아요. 예를 들어, "React 기본 개념" 문서에서 "컴포넌트", "상태 관리", "라이프사이클"에 대한 개요를 제공하고, 각 항목을 별도의 문서로 연결하는 방식이 효과적이에요.
✅ 최대한 구체적인 주제를 다루세요
한 페이지에서 두 개 이상의 핵심 주제를 다루고 있다면 문서를 분리하세요.