편집 원칙: 한 글에는 한 가지 판단만 남긴다¶

이 저장소의 글은 백과사전 항목을 한 페이지에 모으지 않는다. 독자가 실제 업무에서 마주치는 질문 하나를 고르고, 그 질문에 답하는 데 필요한 개념만 기초에서 내부 구조까지 연결한다. 권장 읽기 시간은 6~8분이다. 다만 새 개념이 중요하다는 이유만으로 페이지를 늘리지 않는다. 앞 개념이 뒤 판단을 이해하기 위한 발판이라면 같은 페이지의 앞부분에서 설명한다. 독자가 별도의 질문으로 그 글을 찾아올 때만 독립 문서로 나눈다.

전체 커리큘럼이나 여러 기술 동향의 위치를 보여 주는 페이지는 참조 지도로 구분한다. 참조 지도는 처음부터 끝까지 읽는 글이 아니며 필요한 절을 찾는 역할만 맡는다. 비슷한 정의를 여러 글에 복제하지 않고, 본문에 필요한 만큼만 짧게 다시 설명한 뒤 가장 직접적인 한 글로 연결한다.

제목은 기술 이름보다 질문을 드러낸다¶

데이터베이스 선택보다 PostgreSQL, MySQL, Oracle 중 무엇을 선택할까가 낫다. 독자는 제목만 보고 자신이 얻을 판단을 예상할 수 있어야 한다. 첫 두 문단에는 이 문제가 언제 나타나는지, 잘못 판단하면 무엇을 잃는지, 글이 어떤 결론까지 데려갈지를 적는다.

초보 독자를 배려한다는 이유로 URL이나 API처럼 이미 널리 알려진 단어를 매번 사전처럼 정의하지 않는다. 대신 실제 이해를 막는 단어를 등장한 자리에서 푼다. DNS를 다룬다면 DNS 자체보다 재귀 조회, 리졸버, 권한 있는 이름 서버, CNAME, TTL이 요청 지연과 어떻게 연결되는지를 설명한다. InnoDB를 다룬다면 “저장 엔진”이라는 이름만 주지 말고 MySQL 서버와 역할이 어떻게 나뉘는지 보여 준다.

고정된 공통 목차를 사용하지 않는다¶

문제 배경, 핵심 개념, 내부 흐름 같은 제목을 모든 글에 반복하지 않는다. 목차는 글의 질문에 맞게 정한다. 장애 분석 글은 관측된 증상에서 구간별 측정과 원인 배제로 진행할 수 있고, 제품 선택 글은 이름의 관계, 결론을 바꾸는 조건, 실제 사례, 결정 기록으로 진행할 수 있다. 독자는 목차만 읽어도 논리의 이동을 알 수 있어야 한다.

절의 개수도 미리 정하지 않는다. 비교해야 할 트레이드오프가 네 개면 네 개를 쓰고, 두 개면 두 개만 쓴다. 관련이 약한 내용을 “목차를 채우기 위해” 넣지 않는다. 더 넓은 배경은 별도 글로 연결한다.

한 문단에는 하나의 새 덩어리만 넣는다¶

새 개념을 설명한 문단에서 동시에 예외 세 가지와 운영 지표 다섯 가지를 넣으면 작업 기억이 넘친다. 먼저 개념이 해결하는 문제를 말하고, 다음 문단에서 구조를 설명하며, 그다음 실제 선택에 미치는 영향을 연결한다. 추상적인 설명 뒤에는 가능한 한 가까운 곳에 구체적인 예를 둔다.

같은 결론을 서론·요약·본문·마무리에서 표현만 바꿔 반복하지 않는다. 서론은 질문을 세우고, 본문은 근거를 쌓으며, 마지막은 조건부 결론을 남긴다. 이미 충분히 설명한 정의는 다시 요약하지 않는다.

독자가 다음 문장으로 넘어가기 전에 앞 문장의 숨은 전제를 추론하게 만들지 않는다. InnoDB는 클러스터형 인덱스를 사용한다고 바로 시작하지 않고, MySQL 서버와 저장 엔진이 왜 분리되었는지 먼저 설명한다. EventLoop는 Channel을 처리한다고 시작하지 않고, 연결마다 스레드가 기다리던 구조에서 어떤 비용이 생겼는지 먼저 보여 준다. 설명 순서는 용어의 중요도가 아니라 이해에 필요한 선행 관계를 따른다.

문단은 정의, 구조, 결과를 한꺼번에 담지 않는다. 첫 문단에서 무엇을 위한 개념인지 밝히고, 다음 문단에서 한 요청이 실제로 흐르는 순서를 보여 준다. 그 뒤에야 이 구조가 성능·실패·운영 판단을 어떻게 바꾸는지 설명한다. 독자가 노력해서 재조립하는 글이 아니라, 읽는 순서가 곧 이해 순서가 되어야 한다.

비교는 승자를 고르는 일이 아니다¶

“A는 빠르고 B는 안정적이다”처럼 맥락 없는 형용사를 피한다. 어떤 부하에서 무엇을 측정했는지, 이득을 얻기 위해 어떤 비용을 지불하는지 같은 문장 안에 둔다. 초당 요청 수 하나로 제품을 고르지 않는다. 행 크기, 인덱스 수, 읽기·쓰기 비율, 키 쏠림, 트랜잭션 길이, 내구성 설정, 꼬리 지연과 복제 지연을 함께 본다.

기업 사례는 권위로 결론을 대신하기 위해 쓰지 않는다. 그 회사가 어떤 증상을 관찰했고, 어떤 제약 때문에 선택했으며, 독자의 환경과 무엇이 다른지를 읽는다. 트래픽 수치가 공개되어 있지 않다면 추측해서 채우지 않는다.

그림은 관계가 복잡할 때만 사용한다¶

세 단계 이상의 흐름이나 여러 구성 요소의 책임 경계를 한눈에 보는 데 도움이 될 때 Mermaid 또는 구조도를 사용한다. 그림 안의 영어 이름에는 필요한 한글 역할을 함께 적는다. 문장 하나로 충분한 내용을 장식용 그림으로 만들지 않는다.

모바일에서는 그림 전체가 본문 폭에 먼저 맞아야 한다. 세부 글씨가 있는 경우 기기의 확대 기능을 사용할 수 있게 하되, 본문을 좌우로 밀어내지 않는다. 표는 작은 화면에서 비교 축을 잃기 쉬우므로 사용하지 않고, 판단 기준마다 짧은 절이나 문단으로 풀어 쓴다.

마지막 검토¶

첫 두 문단만 읽어도 글의 질문과 필요 시점을 알 수 있는가?
목차가 이 글에만 맞는 논리 순서를 보여 주는가?
새 개념이 등장하기 전에 그것이 필요한 이유와 선행 개념이 놓였는가?
독자가 문장 사이의 인과 관계를 스스로 보충해야 하는 곳은 없는가?
같은 주장이나 정의를 세 번 이상 반복하지 않았는가?
제품 이름을 지워도 선택을 바꾸는 조건이 남는가?
숫자와 기업 사례는 결론이 아니라 맥락과 제약을 보여 주는가?
낯선 약어는 처음 등장한 자리에서 풀고, 익숙한 기초 단어는 과하게 설명하지 않았는가?
참고 자료 없이도 본문이 완결되며, 외부 링크는 마지막 참고 자료에만 있는가?