📝 블로그 글쓰기 가이드라인 (Writing Style & Rules)

📝 블로그 글쓰기 가이드라인 (Writing Style & Rules)

이 문서는 이 블로그의 필자가 지향하는 글쓰기 스타일과 기술적 서술 방식을 정의합니다. 모든 신규 포스트 작성 및 기존 글 수정 시 이 규칙을 엄격히 준수합니다.

---

1. 글의 구조 및 형식

1.1 제목 작성 (Title)

• 문제 중심: 독자가 직면할 수 있는 구체적인 문제 상황을 명시 (예: “모바일 데이터에서만 발생하는 API 장애 분석”)
• 호기심 유발: 질문이나 대조를 통해 클릭 유도 (예: “ThreadLocal 대신 ScopedValue를 써야 할 이유”)
• 일관성: 시리즈물은 [주제] - [소주제] 형식을 유지

1.2 목차 (TOC)

• 필수 포함: 모든 글 상단에 목차를 배치하여 전체 흐름을 한눈에 파악 가능하게 함
• 계층 구조: 최대 3단계(depth)까지 활용하며, 클릭 시 해당 섹션으로 이동하도록 링크 설정

1.3 본문 흐름 (Template)

기본적으로 다음의 5단계 논리 구조를 따릅니다.

1. 배경/문제 상황: 어떤 현상이 발생했는지 설명
2. 증상/분석: 구체적인 오류 로그나 관찰된 현상 정리
3. 원인 파악: 단계별 가설 검증 및 분석 과정
4. 해결 방법: 구체적인 조치 내용 및 코드
5. 정리/결론: 핵심 요약 및 배운 점

---

2. 문장 스타일 및 어투

2.1 기본 어조

• 정중한 존댓말: ~습니다, ~했습니다를 기본으로 사용
• 우리(We) 중심: 팀 단위 경험을 서술할 때는 저희, 우리 표현 사용
• 개인적 통찰: 주관적인 판단이나 경험은 저는, 제가 보기에는 등으로 구분하여 표현

2.2 시각적 강조 (Emphasis)

• 단독 문장 배치: 핵심 메시지는 줄바꿈 후 한 줄로 배치하여 강조
• 볼드(Bold): 키워드 및 핵심 문장에 적용
• 백틱(`): 기술 용어, 코드 요소, 경로 등에 사용
• 다층적 강조:

  즉,
  **특정 환경에서만 발생하는 장애**
  였고,
  

2.3 문장 연결

• 짧은 단락: 가독성을 위해 한 단락은 2~4문장 이내로 유지
• 명확한 연결어: 즉,, 따라서, 그렇다면, 결과적으로 등을 활용해 논리적 흐름 강화

---

3. 기술 설명 방식

3.1 개념 서술

• 공식 문서 기반: JEP, RFC, 공식 가이드 등을 먼저 인용하고 그 뒤에 본인의 해석을 덧붙임
• 추상 → 구체: 개념 정의 → 필요성(Why) → 동작 방식(How) → 코드 예시 순으로 서술

3.2 사고 과정 공개

• 실패한 시도나 잘못된 가설도 포함하여 독자가 문제 해결의 실마리를 따라올 수 있게 함
• “이 단계에서의 결론은 ~였다”, “따라서 ~를 확인해보기로 했다” 식의 추론 과정을 명시

3.3 시각화 도구

• 표(Table): 비교 분석 시 적극 활용
• Mermaid: 복잡한 아키텍처나 시퀀스는 다이어그램으로 표현

---

4. 코드 및 기술 표현

4.1 코드 블록

• 핵심 중심: 전체 파일보다는 설명에 필요한 부분만 발췌
• 주석 활용: 코드 내부의 핵심 동작을 주석으로 부연 설명
• 순번 표시: 복잡한 실행 순서는 코드 주석이나 상단 리스트에 숫자로 표기

4.2 용어 처리

• 한영 병기: 처음 등장하는 주요 용어는 가상 스레드(Virtual Thread)와 같이 병기
• 약어 풀이: 첫 언급 시 약어의 원형을 명시

---

5. 독자 소통 및 마무리

5.1 소통 유도

• 글 마지막에는 반드시 독자에게 질문을 던지거나 의견을 구하는 문구 삽입
• 예: “혹시 더 좋은 접근 방식이 있다면 댓글로 공유 부탁드립니다!”

5.2 마무리 패턴

• “정리” 섹션: 마지막에 불릿 포인트로 핵심 내용 요약
• 열린 결말: 완벽한 정답보다는 현재의 최선임을 명시하고 향후 개선 가능성 언급

---

📌 핵심 체크리스트 (Write-check)

1. 목차가 포함되었는가?
2. 문제-분석-해결-정리의 흐름을 따르는가?
3. 핵심 문장이 줄바꿈과 볼드로 강조되었는가?
4. 공식 문서 인용과 본인의 해석이 조화로운가?
5. “저희”라는 1인칭 복수형과 존댓말을 유지했는가?