소프트웨어 블로그 글쓰기의 안티패턴

AI 요약

소프트웨어 개발에서 안티패턴을 모아 나쁜 결과를 부르는 흔한 습관을 알아보듯, 글쓰기에도 반복되는 실수가 있습니다. 이 글은 초보 기술 블로거가 독자의 관심과 읽기 흐름을 놓치는 지점을 살펴보고, 글의 전달력을 높이는 방법을 제안합니다.

도입부에서 읽을 이유를 보여주세요

가장 흔한 실수는 글의 목적을 늦게 드러내는 장황한 도입입니다. 개발자는 배경과 역사, 떠오르는 생각을 자세히 쓰고 싶어 하지만, 독자는 첫 문단에서 글이 자신과 관련 있는지, 읽고 어떤 도움을 얻는지 알고 싶어 합니다. 제목과 첫 세 문장 안에 독자가 배울 기술이나 이해할 개념, 얻을 관점을 알려주세요. 부제·자기소개·이미지·인용문도 본문에 도달하기까지 독자가 거쳐야 하는 요소이므로, 집중력을 쓰게 만든다는 점을 고려해야 합니다.

독자의 배경지식을 짐작하지 마세요

Docker를 설명하면서 Linux cgroups나 BSD의 jail을 당연히 안다고 가정하면 입문자에게는 설명이 되지 않습니다. 글을 쓰기 전에 실제로 아는 친구나 동료를 기준 독자로 떠올리고, 익숙한 용어와 낯선 용어를 적어보라고 권합니다. 기술 용어가 나올 때마다 그 독자가 이해할 수 있을지 확인하면 불필요한 가정을 줄일 수 있습니다. 그렇다고 모든 글을 완전 초보자에게 맞추라는 뜻은 아닙니다. 의도한 독자층을 정하고, 그에 맞춰 필요한 지식을 선택해야 합니다.

링크는 보충 자료로 두세요

낯선 개념을 설명하지 않고 링크만 붙이면 독자는 읽던 흐름을 끊고 다른 페이지로 이동해야 합니다. 글 안에서 필요한 최소한의 설명을 먼저 제공하고 링크는 더 깊이 살펴볼 자료로 남기는 편이 좋습니다. 예를 들어 방화벽 설명에 긴 매뉴얼을 연결하는 데 그치지 말고, 방화벽이 호스트와 네트워크 사이의 통신을 제한하며 규칙으로 데이터베이스 서버에 들어오는 요청을 제어한다고 요약할 수 있습니다. 본문은 링크를 누르지 않아도 처음부터 끝까지 이해할 수 있어야 합니다.

후속편이라는 전제를 줄이고, 평소 말투로 쓰세요

이전 글을 읽었다고 가정하며 새 글을 시작하면 새 독자는 읽기 전에 과제를 받은 듯 느낍니다. 앞선 글을 언급해도 괜찮지만, 관련 내용을 짧게 다시 설명해 독립적으로 읽히게 하라고 조언합니다. 글의 상당 부분을 딱딱한 문서체로 쓰기보다 평소 말하듯 간결하고 개성 있게 쓰는 편이 낫습니다. 글쓴이는 AI가 글쓰기를 대신하는 일이 늘면서 글이 개성과 목소리를 잃는다고 지적하며, Joel Spolsky의 구어체 문장을 사례로 듭니다.

모바일 화면과 글자 가독성을 확인하세요

이미지나 코드가 화면 너비를 넘으면 모바일 독자는 좌우로 움직이며 읽어야 합니다. 게시 전에 Firefox나 Chrome의 모바일 미리보기로 확인하라고 권합니다. 글자 색과 배경의 대비도 점검해야 합니다. 브라우저의 접근성 검사 도구를 활용할 수 있고, 시력이 낮은 독자도 읽기 편한 글꼴로 Braille Institute의 Atkinson Hyperlegible을 소개합니다. 글쓴이의 분석에서는 독자 중 25%가 휴대전화로 이 페이지를 읽고, 개인 블로그에서는 비율이 35%에 이릅니다.

Lobsters 반응

• @legoktm — 두 가지 안티패턴을 더하고 싶습니다. 글 맨 위에 작성 날짜를 표시하지 않는 것, 각주가 선택 사항이 아니라 사실상 필수 읽을거리가 되는 것입니다. 링크에 관한 지적과 비슷합니다.
  • @simonw — 날짜를 아예 표시하지 않는 경우도 너무 많습니다. 날짜를 알아내려고 페이지 소스를 뒤지거나, 실패하면 Internet Archive에서 가장 오래된 기록을 찾아봅니다. 게시 시점은 글쓴이의 관점을 이해하는 데 중요한 맥락입니다.
  • @rprospero — 월과 일만 있고 연도가 없는 글보다는 날짜가 없는 편이 낫다고 느낄 때도 있습니다. “10월 1일 게시”라는 글이 지난주에 쓰였는지 시드니 올림픽 폐막식 즈음에 쓰였는지 알 수 없습니다.
• @mcherm — 가장 큰 안티패턴은 블로그 플랫폼을 만드는 데 두 달을 쓰고, 첫 글로 자기소개와 앞으로 쓸 주제를 설명하는 데 두 시간을 쓴 다음 아무것도 올리지 않는 것입니다. 꾸준히 쓰는 것만으로도 이미 상위 5%, 어쩌면 1%에 들 수 있습니다. 더 잘 쓸 여지는 있지만, 이미 하고 있는 일도 축하해야 합니다.
  • @cceckman — 공개한 글에 쓴 시간은 플러스로, 사이트 기술 작업에 쓴 시간은 마이너스로 더해 합계를 계속 양수로 유지하려고 합니다. 첫 글에 한 시간 썼다면 이제 정적 사이트 생성기(SSG)를 설정하는 데 한 시간을 써도 됩니다. 사이트 디자인에 한 시간을 썼다면 코드 작성에 한 시간을 쓰면 됩니다.
  • @vbernat — 블로그 코드를 손보는 일도 즐깁니다. 블로그는 제일 개인적인 프로젝트이고, 의존하는 사람도 저뿐입니다. 글쓰기를 피하려고 기술 작업에 빠지는 경우도 있지만, 블로그가 취미라면 나쁘다고 생각하지 않습니다.
• @simonw — 장황한 도입에는 역피라미드 방식이 도움이 됩니다. 많은 독자가 첫 문단 뒤에는 읽지 않는다고 생각하고, 핵심 메시지를 첫 문단에 담으세요. 형식적인 말투를 버리고 자기 목소리를 쓰라는 조언에도 전적으로 동의합니다. LLM 글쓰기는 그 목소리를 없애고, 독자는 그 차이를 알아봅니다.
  • @mtlynch — 링크를 많이 다는 것 자체가 문제는 아니라고 봅니다. 링크를 누르지 않아도 글이 이해되어야 한다는 것이 제 기준입니다. 독자가 더 깊이 살펴보도록 링크를 제공하되, 모두 읽으리라 기대하지 않는 방식입니다.
  • @hibachrach — 여기서 중요한 말은 ‘의존’입니다. 참고 링크를 읽어야 다음 내용을 이해할 수 있다면, 하이퍼링크를 만날 때마다 비동기 런타임의 await처럼 작업 전환을 하는 느낌이 듭니다.
• @amw-zero — “독자의 배경지식에 관한 가정을 줄이라”는 말은 “독자와 독자의 배경지식을 파악하라”고 표현하는 편이 낫습니다. 독자를 언제나 완전 초보자로 가정해도 좋은 글이 나오지는 않습니다.
• @purplesyringa — 대체로 동의하지만, 규칙마다 예외가 있다는 점도 말해야 합니다. 독자가 글쓴이의 개성을 좋아하거나 무엇을 하는지 궁금해한다면, 사실을 바로 말하는 방식이 아니어도 글을 읽게 할 수 있습니다. 독자의 배경지식을 줄여 가정하라는 조언도 가장 낮은 수준에 맞추라는 뜻은 아닙니다. 독자를 의식적으로 정하고, 필요한 만큼 깊게 쓰면 됩니다.
• @facundoolano — 제가 즐겨 쓰는 방법은 첫 문단 전체를 잘라내도 글이 잘 읽히는지 확인하는 것입니다. 읽힌다면 그 문단은 없는 편이 나을 수 있습니다. 그다음에도 반복합니다.
• @toastal — 블로그를 읽으려면 JavaScript가 필수인 경우, 기술 독자를 겨냥하지 않았다는 좋은 신호라고 생각합니다. JavaScript를 꺼두거나 허용 목록 방식으로 쓰는 독자도 많습니다. 최소한 무엇을 놓치게 되는지 설명하는 noscript 메시지라도 보여주세요.
• @bensheldon — 기술자는 기술 내용을 담은 이야기를 쓸 수도 있습니다. 모든 글이 교훈을 주거나 유용한 지식을 차려서 내놓아야 하는 것은 아닙니다. Rachel by the Bay나 The DailyWTF처럼 이야기 자체가 좋은 기술 블로그도 있습니다. 이런 글쓰기 규칙이 경고하는 좋은 기술 콘텐츠도 필요하지만, 더 많은 사람이 이야기를 써보기를 바랍니다.

원문: Refactoring English / 번역·요약: Trawling