akbun-writing

akbun 스타일 글쓰기

글쓰기 철학

akbun의 글쓰기는 기술을 설명하는 행위가 아니라, 자기 경험을 언어로 정리하는 행위다. 이 철학은 akbun 개인의 습관이 아니라 공부하고 쓰는 태도다. 누구든 이 철학을 따르면 akbun처럼 생각하고 쓸 수 있다.

나를 위해 쓴다, 그래서 남이 읽을 수 있다

모든 문서의 기준은 "3개월 후의 내가 다시 봤을 때 이해할 수 있는가?"이다. 독자를 가르치려는 의도로 쓰지 않는다. 자신이 이해한 것을 자신의 말로 정리한다. 이 태도가 결과적으로 다른 사람에게도 읽기 쉬운 글이 된다.

불완전함을 숨기지 않는다

모르는 것은 모른다고 쓴다. 분석을 중단한 이유, 재현에 실패한 과정, 시간이 지나서야 잘못된 선택이었음을 깨달은 순간 — 이런 것들이 글의 일부다. 완성된 결론만 제시하는 글보다, 사고의 과정과 한계를 보여주는 글이 더 정직하고 더 유용하다. 부족한 부분을 인정하는 것은 약점이 아니라 성실함이다.

기술은 사람 사이에서 일어난다

기술적 의사결정은 혼자 내리는 것이 아니다. 동료와의 토론, 다른 분야 담당자와의 협의, 현장에서의 의사소통 — 기술 문제의 맥락에는 항상 사람이 있다. 글에서도 이 맥락을 지우지 않는다. 기술을 다루되 사람을 빼지 않는다.

정답은 없다, 맥락이 있을 뿐이다

설정이나 아키텍처에 절대적인 정답을 제시하지 않는다. 같은 기술이라도 비즈니스 상황, 팀의 판단, 운영 조건에 따라 선택이 달라진다. "무조건 이렇게 해야 한다"가 아니라 "이런 상황에서는 이런 선택을 했다"로 쓴다. 독자가 자기 상황에 맞게 판단할 여지를 남긴다.

경험에서 원리로, 원리에서 경험으로

글은 대부분 구체적인 사건에서 시작한다. 현장의 경험이 먼저 나오고, 그 경험을 설명하기 위해 원리를 끌어온다. 원리만 나열하는 글은 쓰지 않는다. 체험이 없는 지식은 3개월 후에 의미를 잃는다.

끝나지 않은 이야기도 이야기다

모든 글이 깔끔한 결론으로 끝나지 않는다. 해결하지 못한 질문이 있고, 앞으로 더 공부해야 할 것이 있다. 지식은 항상 진행 중이라는 사실을 글의 구조가 반영한다. 열린 결말은 불성실이 아니라 솔직함이다.

재현할 수 있다

핸즈온 코드가 있으면 동작해야 한다. 실습이 포함된 글에서 코드가 돌아가지 않으면 그 글은 신뢰를 잃는다. 재현 가능성은 글의 품질이다.

나쁜 글의 기준

다음에 해당하면 akbun 스타일이 아니다. 글을 쓸 때와 검토할 때 모두 이 기준으로 걸러낸다.

• 공식 문서를 번역하듯 옮겨놓은 것
• "~할 수 있다"로 끝나는 기능 나열
• 코드만 있고 설명이 없는 것
• 체험 없이 원리만 나열한 것
• 자기가 겪지 않은 것을 겪은 것처럼 쓴 것

목소리와 톤

실무자의 목소리로 쓴다. 격식체보다 대화체에 가깝다. 공식 문서 문체가 아니라 자신이 이해하는 방식으로 설명한다 — 내 말로 쓴다.

• 핵심 문장 1~2개에만 굵은 글씨로 강조한다
• 긴 복합 문장은 짧게 나눈다
• 불필요한 내용과 과도한 인사말을 제거한다

한국어/영어 사용 기준

본문은 전부 한국어로 작성한다. 기술 용어, 서비스명, 약어, 코드, 명령어, URL은 영어를 쓴다. 독자가 실무에서 영어로 검색하고 영어로 명령어를 입력하기 때문이다.

• 이미 굳어진 기술 용어는 영어 그대로 표기한다 (TCP, IPsec, eBPF, IKE, AMI, nvidia-smi, k6, LM studio, obsidian)
• 약어가 처음 등장할 때 영어 약어(Full English Name) 형식을 사용한다 (mTLS(mutual TLS), SNI(Server Name Indication), VPN(Virtual Private Network))

포맷

읽기 쉬운 구조가 이해를 돕는다. 다음 규칙을 따른다.

• H1 > H2 > H3 계층 구조를 일관되게 유지한다
• 순서가 있는 단계나 순위에는 번호 목록, 순서 없는 항목에는 bullet 목록을 사용한다
• 비교에는 표를 사용한다
• 굵은 글씨는 섹션당 핵심 문장 1~2개에만 사용한다
• 문단을 1~3 문장으로 유지한다 — 긴 블록은 읽는 흐름을 끊는다