Anti-Patterns in Software Blogging

3줄 요약

1. 마이클 린치(Michael Lynch)가 2026년 10월 7일, 기술 블로그를 처음 쓰는 개발자들이 반복하는 실수를 정리했다. 도입부와 설명 방식, 말투와 웹페이지까지 독자가 글을 읽는 데 영향을 주는 요소를 다룬다.¹
2. 누구를 위한 글이고 무엇을 얻을 수 있는지 먼저 밝혀야 한다. 낯선 용어와 전편의 내용은 필요한 만큼 설명해서, 독자가 다른 글을 먼저 읽어야 하는 상황을 줄인다.
3. 자연스럽게 말하듯 쓰는 것과 편하게 읽히는 화면을 만드는 것도 글쓰기의 일부다. 좋은 내용을 준비했더라도 설명이 부족하면 독자는 내용을 이해하기 어렵다. 모바일에서 본문이 잘리면 글을 계속 읽기도 어렵다.

글을 읽기 시작한 사람

기술 블로그를 쓰는 개발자는 자신이 문제를 해결한 과정을 잘 안다. 무엇 때문에 이 일을 시작했는지, 어떤 도구를 사용했는지, 왜 다른 방법은 쓰지 않았는지 설명하고 싶은 것도 많다. 하지만 글을 처음 읽는 사람에게는 왜 그 이야기를 계속 읽어야 하는지부터 알려 줘야 한다.

린치는 제목과 첫 세 문장에서 누구를 위한 글인지, 읽으면 무엇을 얻을 수 있는지 알려야 한다고 했다. 새 기술을 배우게 해도 좋고, 익숙한 문제를 다른 관점에서 생각하게 해도 좋다. 배경 설명을 길게 읽은 뒤에야 글의 주제를 알 수 있다면, 독자는 자신에게 필요한 글인지 판단하기 어렵다.

린치가 직접 쓴 Go 테스트 글은 제목에서부터 테스트를 더 잘 작성하는 방법을 소개한다. 첫 문장에서는 30초 만에 배울 수 있는 패턴이라고 소개한다. Go를 사용하는 개발자는 이 글이 자신의 업무와 관련 있다는 것을 알 수 있다. 오래 읽지 않고도 간단한 방법을 배워 볼 수 있다.²

그 글에서는 실제 값을 got, 기대 값을 want라는 이름으로 표시하고 두 값을 비교한다. 이름을 일관되게 쓰면 코드의 어느 부분이 테스트 결과를 확인하는지 알아보기 쉽다. 도입부에서 배우게 된다고 약속한 방법을 본문에서 구체적으로 설명한다. 막연히 유용하다고 소개하는 것보다 무엇을 배우게 되는지 정확히 알려 준다.

도입부를 확인할 때에는 본문 앞에 표시되는 요소도 함께 살펴볼 필요가 있다. 본문 전에 부제와 자기소개, 이미지가 있다면 독자는 그것부터 읽고 살펴본다. 각각은 짧더라도 여러 요소가 이어지면 본문을 시작하기까지 시간이 걸린다. 글이 독자에게 약속한 내용을 실제로 얼마나 빨리 설명하는지도 함께 확인해야 한다.

내가 아는 것과 독자가 아는 것

개발자라는 직업만으로 배경지식을 짐작하기는 어렵다. 웹 화면을 만드는 데 익숙한 사람과 운영체제를 다루는 데 익숙한 사람은 자주 사용하는 용어부터 다르다. 새 개념을 설명하면서 또 다른 생소한 개념을 비교 대상으로 쓰면, 독자는 설명을 이해하려고 그 개념까지 알아야 한다.

원문의 Docker 입문 예시에는 Linux의 cgroups와 BSD의 jails가 등장한다. Docker를 처음 접하는 사람도 다른 운영체제의 기능을 이미 알고 있다고 가정한 설명이다. 용어를 이미 아는 사람에게는 짧은 설명이겠지만, 모르는 사람에게는 무엇을 하는 도구인지조차 알려 주지 못한다.

Docker는 애플리케이션과 실행에 필요한 구성 요소를 컨테이너라는 격리된 환경으로 묶어 배포하고 실행하는 도구다. 개발자의 컴퓨터와 테스트 환경, 운영 환경에서 같은 구성을 사용하려는 것이다. Docker 공식 소개도 이 용도부터 설명한 뒤 구조와 내부 기술을 다룬다.³ 입문자가 먼저 알아야 할 것은 도구로 무엇을 할 수 있는지다. 내부 구현을 설명하는 데 필요한 지식은 그다음에 제공할 수 있다.

여기서 린치가 권하는 방법은 실제 친구나 동료 한 사람을 독자로 정하는 것이다. 그 사람이 아는 용어와 모르는 용어를 적고 초안과 대조한다. 막연히 초급자나 개발자를 상상할 때보다, 어느 단어에 설명이 필요한지 판단하기 쉽다.

독자가 알아야 할 것이 많다는 이유로 입문 설명을 끝없이 늘릴 필요는 없다. 먼저 그 글을 이해하는 데 꼭 필요한 내용이 무엇인지 구체적으로 정해야 한다. 독자가 이미 아는 내용이 무엇인지도 확인해야 한다. 글쓴이가 잘 아는 내용이라 설명을 생략했다면, 독자도 그 내용을 아는지 별도로 확인해야 한다.

링크를 누르기 전에

용어에 관련 자료의 링크를 제공하면 독자가 출처를 확인하거나 자세히 공부할 수 있다. 하지만 낯선 단어를 이해하기 위해 다른 페이지를 읽어야 한다면, 독자는 원래 글에서 하던 생각을 잠시 중단해야 한다. 그 자료를 얼마나 읽어야 하는지까지 스스로 판단해야 한다.

린치는 방화벽을 설명하면서 FreeBSD 매뉴얼의 링크를 제공하는 사례를 든다. 매뉴얼에는 패킷 필터링, 여러 방화벽 도구, 규칙 설정 등이 자세히 설명돼 있다. 방화벽을 실제로 설정하려는 사람에게 필요한 자료지만, 글의 한 문장을 이해하려는 사람은 그 문장에 필요한 설명보다 훨씬 많은 내용을 읽어야 할 수 있다.⁴

방화벽은 네트워크 통신을 규칙에 따라 허용하거나 차단한다. 예를 들어 데이터베이스를 인터넷에 직접 공개하지 않고 애플리케이션 서버에서 오는 통신만 허용하려면, 어떤 통신을 허용할지 규칙으로 정한다. 이런 설명이 있으면 독자는 방화벽이 그 문맥에서 무엇을 하는지 이해할 수 있다. 사용하는 운영체제의 설정 방법까지 필요해졌을 때 매뉴얼을 참고하면 된다.

필요한 설명이 빠진 글에 링크를 추가해도, 독자는 여전히 다른 자료를 읽어야 내용을 이해할 수 있다. 본문을 이해하는 데 필요한 내용은 본문에서 설명하고, 링크는 자세히 알아보려는 독자에게 제공해야 한다. 출처를 남기는 일과 독자가 이해하도록 쓰는 일은 둘 다 해야 한다.

전편을 읽지 않은 독자

후속 글을 읽다가 처음 보는 용어가 등장하면 전편을 찾아 읽어야 할 수도 있다. 글쓴이는 전편에서 무엇을 설명했는지 기억하지만, 지금 읽는 사람은 검색이나 다른 사람의 공유를 통해 처음 찾아왔을 수 있다. 글쓴이가 설명을 생략한 용어는 그 사람에게도 익숙할까.

후속 글에는 지금 내용과 관련된 설명을 다시 제공하면 된다. 앞선 실험의 결과를 활용한다면 어떤 조건에서 어떤 결과를 얻었는지 요약한다. 이전에 작성한 코드가 필요하다면 그 코드의 역할을 알려 준다. 전편에서 다룬 내용을 모두 반복할 필요는 없다. 이번 내용과 관련된 부분을 설명하면 된다.

여러 편이 필요한 큰 프로젝트도 있다. 그래도 글쓴이가 작성한 순서대로 독자도 읽을 것이라고 기대하기는 어렵다. 그 글에서 무엇을 설명하는지, 이해하는 데 어떤 지식이 필요한지 먼저 알 수 있어야 한다.

평소에 말하는 방식

격식을 갖추려고 문장을 어렵게 쓰면, 누가 무엇을 했는지 이해하는 데 시간이 걸린다. 여러 정적 분석기를 써 본 경험을 이야기하면서, 프로젝트를 진행한 전체 기간이나 누가 참여했는지를 복잡하게 표현할 필요는 없다. 정적 분석기는 코드를 실행하지 않고 문제를 검사하는 도구다. 독자는 어떤 도구를 사용했는지, 그 도구로 무엇을 알아냈는지 궁금해할 것이다.

린치는 평소 말하는 방식으로 쓰라고 권했다. AI에 글쓰기를 맡기는 개발자가 많아지면서 기술 블로그의 개성이 부족해졌다는 지적도 했다. 그는 조엘 스폴스키(Joel Spolsky)를 비롯한 필자들의 글에서 친구에게 이야기를 들려주는 듯한 말투를 높이 평가한다.

원문에서 소개한 스폴스키의 글은 컴퓨터공학 교육에 대한 의견을 학생들의 경험으로 설명한다. 어릴 때 게임을 만들던 학생이 대학에서 포인터를 배우며 어려움을 겪는 이야기다.⁵ 스폴스키는 기술적 주장을 설명하면서 학생이 무엇을 하고 어떻게 반응하는지도 구체적으로 적는다. 격식을 줄인 글에서도 무엇을 말하려는지 분명하게 설명할 수 있다.

휴대전화로 읽을 때

글을 쓰며 확인한 화면은 대개 컴퓨터의 넓은 화면이다. 휴대전화에서는 같은 글이 어떻게 표시되는지도 확인해야 한다. 폭이 큰 이미지나 긴 코드 때문에 본문까지 화면보다 넓어지면, 독자는 한 줄을 읽을 때마다 좌우로 화면을 이동해야 한다. 글을 다 쓴 뒤에는 좁은 화면에서도 본문을 계속 읽을 수 있는지 확인해야 한다.

그림을 크게 보려고 확대하거나 코드 블록만 가로로 스크롤하는 것과, 본문 전체를 좌우로 이동하며 읽는 것은 경험이 다르다. W3C의 접근성 설명도 지도나 표와 일반 본문을 구분한다. 지도나 표는 내용을 이해하려면 가로와 세로의 배치를 함께 보아야 하는 콘텐츠다. 일부 콘텐츠에 가로 스크롤이 필요하더라도 주변 문단은 화면 폭에 맞춰 읽을 수 있어야 한다.⁶

글자색과 배경색도 함께 확인해야 한다. 연한 회색 배경에 진한 회색 글자를 사용하면 차분해 보일 수 있지만, 색의 대비가 부족하면 읽기 어렵다. 브라우저의 접근성 도구로 대비를 점검할 수 있다. 색을 선택한 의도보다 실제 글자가 잘 구별되는지가 중요하다.⁷

읽고 나서

나는 용어의 출처를 명시하고 나면 그 용어를 충분히 설명했다고 생각하기 쉽다. 내가 다시 읽을 때는 이미 그 용어를 알고 있다. 그 때문에 독자가 링크를 누르지 않고도 이해할 수 있는지 확인하지 못하기 쉽다. 실제 친구나 동료 한 사람을 독자로 정하고, 그 사람이 아는 용어를 적어 보라는 제안이 특히 유용했다. 누구를 위한 글인지 정한 뒤에도 그 사람이 내용을 이해할 수 있는지 문장마다 다시 확인해야 했다.

글을 짧게 만드는 것도 비슷하다. 설명을 줄이면 읽는 시간은 줄지만, 독자가 이해하는 데 필요한 내용을 삭제했을 수도 있다. 다음 초안에서는 어떤 문장을 삭제할지 결정하기 전에, 그 문장을 삭제하면 독자가 어떤 내용을 이해하기 어려울지부터 확인하고 싶다.

출처

Michael Lynch, Refactoring English, 2026-10-07.

원문: Anti-Patterns in Software Blogging

커버 삽화: Piotr Letachowicz, 원문 「What the Reader Knows」.