요약
개발자 블로그 글을 망치는 흔한 실수 여섯 가지와 고치는 법을 정리했습니다.
개발자를 위한 글쓰기 책을 낸 마이클 린치가 자신의 블로그 Refactoring English에 쓴 글입니다. 소프트웨어의 안티패턴(흔히 되풀이되는 나쁜 설계 방식)이라는 개념을 빌려, 초보 블로거가 자주 빠지는 함정을 하나씩 짚었습니다.
왜 중요한가
- 읽을거리가 넘치는 독자는 첫머리만 보고 떠날지 정하므로, 좋은 내용도 도입부에서 묻힐 수 있습니다.
- AI가 쓴 글로 블로그가 밋밋하고 비슷해질수록 글쓴이의 개성이 더 큰 강점이 된다고 봤습니다.
핵심 내용
- 가장 흔한 실수는 장황한 도입부이며, 제목과 첫 세 문장 안에 독자가 얻을 것을 밝히라고 했습니다.
- 독자가 내 배경지식을 다 안다고 가정하지 말고, 실제 동료를 떠올려 그가 모를 용어를 점검하라고 권했습니다.
- 용어 설명은 링크로, 앞 내용은 이전 편으로 떠넘기지 말고 글 하나로 완결되게 쓰라고 했습니다.
- 딱딱한 관료식 문장 대신 말하듯 쓰라며, 조엘 스폴스키를 본보기로 들었습니다.
- 독자의 25~35%가 휴대폰으로 읽는다며, 발행 전에 화면 밖으로 넘치는 요소와 글자 대비를 점검하라고 했습니다.
HN 반응
- 설명하는 글은 결론부터 말해야 한다는 주장에, 독자가 여유롭게 읽을 때는 이야기로 풀어 가는 글도 효과적이라는 반론이 맞섰습니다.
- 기술 블로그에도 요리 블로그의 '레시피로 건너뛰기' 버튼이 필요하다는 불만과 함께, LLM이 쓴 글이 지나치게 길다는 지적이 이어졌습니다.
저는 교육이 스토리텔링이 아니며 그렇게 짜서도 안 된다고 늘 주장합니다. 사람들은 최대한의 효과를 내려고 "반전"과 "폭로"를 아껴 두고 싶어 하는데, 그건 해롭습니다. 오히려 그 반대여야 합니다. 이 주제에 맞춰 말하자면 "스포일러투성이"에 반복적이어야 하죠. 좋은 발표처럼 먼저 무엇을 말할지 말하고, 말하고, 마지막으로 무엇을 말했는지 말하며 마무리해야 합니다.
LLM 때문에 이 문제는 훨씬 심해졌습니다. MCP가 뭔지 기술적으로 몇 마디에 설명한다고 상상해 보고, 그걸 직접 검색해 보세요. 전화번호부 분량의 페이지와 글이 나오는데, 끝내 요점에는 도달하지 않습니다.
교육이 스토리텔링이 아니라는 데는 동의하지만, 스토리텔링이 교육에 유용한 도구가 될 수는 있다고 생각합니다.
Paul Graham과 Joel Spolsky의 글 중 상당수는 곧바로 요점으로 들어가지 않고, 대개 서론 -> 본론 -> 결론 형식도 따르지 않습니다. 글이 어디로 향하는지 알 수 없는 이야기로 시작하거나[0], 가치가 바로 드러나지 않는 긴 곁가지가 들어 있는 경우가 많죠.[1]
저는 한동안 이 모순 때문에 고민했습니다. 좋은 글이라면 독자가 무엇을 얻어 갈지 빨리 보여 줘야 한다고 생각하는데, Graham과 Spolsky는 요점에 이르기까지 자주 뜸을 들이는데도 훌륭한 필자라고 생각했거든요.
쉬운 답은 두 사람이 유명해서 뭘 하든 사람들이 읽어 준다는 것입니다. 그런데 지금은 이렇게 생각합니다. Graham이나 Spolsky 같은 필자들은 글 자체의 수준이 워낙 높아서, 어떤 요점을 말할지 몰라도 계속 읽게 만드는 것이 바로 그 글의 가치라고요.
[0] https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/
[1] https://paulgraham.com/worked.html
저는 Joel과 Paul의 블로그가 교육이 아니라 의견을 담은 글이라고 봅니다. 그 의견 중 상당수가 시간이 지나며 널리 받아들여졌다고 해서 형식이 바뀌는 것은 아닙니다. 이 글들은 (교과서나 과학 논문처럼) 순수하게 정보를 전달하는 글이 아니라 논증하는 글입니다.
바로 그 점을 이 글이 놓치고 있습니다. 특정 유형의 글에는 맞을 수 있어도 다른 유형에는 맞지 않을 수 있는 주장을 뭉뚱그려 단정하고 있습니다.
제 생각에 글쓰기 조언의 0번 규칙은 모든 글쓰기 조언을 가려서 듣고, 맥락과 독자를 함께 살피라는 것입니다.
독자들은 오랜 세월에 걸쳐 Joel과 Paul에게서 무엇을 기대할 수 있는지 알게 됐고, 덕분에 두 사람은 자기 방식대로 계속 쓸 자유를 얻었습니다. 같은 글이 오늘날에는 어떻게 받아들여질지 궁금합니다. 환경이 매우 다르잖아요. 훨씬 붐비고, 열린 웹보다 소셜 미디어가 판을 좌우하고, 관심이 영상으로 옮겨 간 것은 말할 것도 없고요. 이전 시대의 기술 블로거들이 쌓아 올린 만큼의 관심을 오늘날의 필자들이 얻을 수 있다고는 생각하지 않습니다.
독자에게 맞는 형식을 혼동하고 계신 것 같습니다. 가볍게 읽을거리를 찾는 사람은 배움이 살짝 곁들여진 재미있는 글을 선호하고, 무언가를 배우려는 사람은 당신의 문체와 서술 방식에 짜증을 낼 겁니다. 당신이 쓰는 글은, 좋든 싫든, 특정한 마음 상태에 있는 사람을 겨냥합니다. 배우려는 마음으로 온 사람은 그 빌어먹을 레시피를 읽는 중에 당신 할머니 이야기를 듣고 싶어 하지 않습니다.
그것도 하나의 요인이라고 생각합니다. 독자가 구체적인 목표를 갖고 있고 블로그 글이 그 목표를 달성하는 방법으로 제시되어 있다면, 독자는 이야기에 대한 인내심이 떨어질 겁니다.
하지만 Spolsky의 "Things You Should Never Do"를 예로 들면, 누가 "하면 안 되는 것들"을 구글에 검색해서 Joel의 글을 클릭하고는 곧바로 알려 주지 않는다고 Joel에게 화를 내겠습니까? 그런 사람들은 HN, RSS 리더, 포럼 같은 곳에서 그 글을 발견합니다. 배움이나 재미 말고는 특별한 목표가 없었던 사람들이니, 필자가 뜸을 들일 여지가 더 있는 거죠.
저는 StackOverflow에 달린 비꼬는 식의 비답변을 수없이 따라가다가 Joel Spolsky의 블로그를 알게 됐어요. 저만 그런 건 아닐 겁니다.
2000년대에 컴퓨터를 접하며 자란 어떤 층에게는 이런 글이 전부 잘난 척하는 쓰레기였고, 진지하게 배우려는 사람을 가로막는 것이었죠. 높은 데서 우리를 비웃는 사람들이었어요.
Joel의 글이 좋아진 건 직장 생활을 몇 년 한 뒤였습니다.
학부 시절 연구 지도교수님이 "논문과 발표는 추리소설이 아니다"라고 말씀하셨습니다. 저는 설명하는 글을 쓸 때마다 이 말을 떠올리려 합니다. 목적은 청중이 당신이 도착한 곳을 이해하도록 돕는 것이지, 당신이 겪은 깨달음의 순간을 그대로 재현하는 것이 아니니까요.
하하. 제 지도교수님은 졸업 심사 전에 말 그대로 이렇게 말씀하셨습니다. "심사위원들은 네 논문에서 네가 한 부분만 빼고 수학은 전부 안다고 가정해라. 그러니 그 부분을 설명해라. '오류 정정 부호'가 뭔지 설명하느라 시간 쓰지 말고, 네가 만든 구체적인 구성과 네가 밝혀낸 실질적인 한계를 말해라." 이게 바로 "독자는 이 한 가지만 빼고 내가 아는 건 전부 안다"는 안티패턴이라고 할 수 있겠지만, 그래도 블로그는 학회 발표와 다르지 않나요?
네, 청중이 사전 지식을 얼마나 갖췄다고 가정할지 정하는 일은 정보를 잘 전달하는 데서 가장 어려운 부분 가운데 하나라고 생각합니다. 정보를 너무 많이 주면 지루하거나 훈계하는 사람으로 보이고, 충분히 주지 않으면 청중 대부분(전부는 아니더라도)이 금세 흥미를 잃습니다. 그런데 모든 것은 그 순간의 정확한 청중에 맞춰야 하고, 그걸 헤아리기란 대개 정말 어렵습니다.
글을 쓸 때는 다른 글로 링크를 걸 수 있다는 이점이 있습니다. 원칙적으로 학술 인용은 DAG를 이루기 때문에, 어떤 논문이든 선행 지식을 전부 따라가 이해할 수 있습니다. 논문은 상식이 아닌 의존 대상을 모두 인용해야 하지만, 그것을 다시 설명할 필요는 없습니다.
꼭 DAG는 아닐 수도 있어요. 제 분야의 한 동료는 서로를 인용하는 논문 두 편을 같은 학회에 동시에 통과시켰거든요. 누군가의 출판물 크롤러는 분명 이 때문에 속이 꽤 상했을 겁니다.
고2 때 잘난 척하던 애가 있었는데, 같은 에세이 안에서 자기 에세이를 인용했습니다. 인용 형식은 제대로 갖췄다고 점수를 받았지만, 1차 자료가 아니라는 이유로 감점도 당했죠.
맞습니다. 좋은 (인간 사이의) 소통은 결국 필자와 독자가 서로에 대한 마음 이론(theory of mind)을 갖는 일로 귀결됩니다. 필자는 독자가 무슨 생각을 할지 예상해야 하고, 독자는 필자가 무엇을 전하고 싶었는지 상상해야[0] 합니다.
요즘 LLM이 쏟아내는 쓰레기 글(slop)이 그토록 짜증스러운 이유 중 하나가 이겁니다. 형식을 제대로 갖춘 단어들 때문에, 애초에 존재하지도 않았던 마음을 재구성하느라 우리가 노력을 낭비하게 되거든요. 일부 동물이 먹을 수도 짝짓기할 수도 없는 아주 실감 나는 플라스틱 모형을 맞닥뜨리는 것과 비슷합니다.
오, 그렇게 문제를 설명하는 방식이 마음에 드네요. 기억해 둬야겠어요!
학회에서는 제가 본 건 정반대였어요. 수학과 생물학이 달라서 그럴 수도 있지만요.
최악의 발표는 늘 모든 실험 기법과 지식을 청중이 다 안다고 전제하는 발표였습니다. 저는 청중이 많아야 해당 분야 석사 수준이라고 보고, 짧게라도 모든 걸 설명하려고 했습니다.
논문은 동료를 대상으로 쓰는 글입니다. 동료에게는 논문이 "추리소설"일 필요가 없습니다(그렇다고 이야기를 들려주지 말아야 한다는 뜻은 아닙니다). 독자에 맞춰 써야 합니다. 논문을 동료가 아니라 일반 대중에게 맞춰 쓴다면 모든 논문이 소설책 분량이 되어야 할 겁니다.
솔직히 arxiv 논문을 다룬 HN 댓글을 보면 가끔 답답합니다. 괴짜들이 모인 포럼이라도 대부분의 논문은 이 독자층을 위해 쓰인 것이 아닙니다. 저는 박사 학위가 있지만 대부분의 논문은 저를 위해 쓰인 것도 아닙니다. 그래야 할 이유도 없고요. 논문을 이해하지 못해도 저는 전혀 괜찮습니다. 박사 과정에서 가장 어려운 점은, 어쩌면 자신이 모른다는 사실을 편하게 받아들이고 덜 모르는 사람이 되려고 계속 노력하는 법을 배우는 것일지도 모릅니다(아예 모르지 않는 때는 없고, 덜 모를 뿐입니다).
맞는 말씀입니다. 다만 과학 논문의 글이 너무 난해한 쪽으로 치우치는 경우가 많다고 생각합니다. 적어도 머신러닝에서는 기념비적인 논문 상당수가 제가 평소 읽는 대부분의 논문과 달리 놀라울 만큼 명료하고 단순합니다. 문제 설정 같은 단순한 부분조차 훌륭한 논문에서는 통찰력 있게 쓸 수 있습니다.
수학 논문을 읽어 보세요 ㅋㅋ
솔직히 저는 반대로 느낍니다. 제 박사 전공이 ML이라서 그럴 수도 있겠네요. 아니면 대표 논문이 뭔지에 대한 정의가 서로 다를 수도 있고요. 유명한 논문 중 상당수는 기존 방법을 스케일업한 모델입니다(ViT와 ddpm이 좋은 예입니다). 중요한 논문이긴 한데, 어떤 면에서 중요할까요? 저는 모든 종류의 논문이 있어야 하고 서로 다른 독자를 위해 쓰여도 된다고 생각합니다. 다만 자기 틈새 분야에 맞춰 썼다는 이유로 논문에 벌을 줘선 안 된다고 봅니다. 지난 10년간 인용 농사가 크게 늘었는데, 이것도 도움이 안 된다고 생각해요. 수학은 아마 한쪽 극단이 너무 심하고, ML은 그 반대쪽 극단일 겁니다. 박사 1년차가 이해할 수 있게 논문을 써야 하죠. 그 사람들이 여러분의 연구를 심사하니까요. 바람직한 결과라고는 생각하지 않습니다.
제 생각에 이건 유명하거나 획기적인 논문일수록 실제로 읽기 전에 여러 다른 곳에서 먼저 설명을 듣게 되기 때문이기도 합니다. 그래서 원문을 읽기 전부터 이미 잘 이해하게 되는 거죠.
예를 들어 Einstein이 특수상대성이론을 발표한 논문들은 정말 읽기 괴롭지만, (당대 사람들) 대부분은 원문을 읽기 전에 이미 그 내용을 잘 알고 있었습니다.
저는 "A rational design process, how and why to fake it"[0]라는 논문을 받았는데, 지금도 제가 가장 좋아하는 논문 중 하나입니다. 요지는 문서를 쓸 때, 세상이 완전히 합리적이었다면 있었을 자리로 나중에 알게 된 사실을 돌려놓으라는 겁니다. 이리저리 돌아간 과정과 뒤늦은 발견은 전부 빼 버리세요. 신경 쓰는 사람은 거의 없습니다. 모든 것과 모든 사람이 완전히 합리적이었고 적절한 때에 모든 지식을 갖고 있었던 것처럼 문서를 소급해서 고치는 겁니다. 문서 분량을 크게 줄일 수 있습니다.
main에 머지하기 전에 squash하고 rebase하는 것 같은 건가요?
제 박사 지도교수님도 비슷한 말씀을 하셨는데, 논문은 이야기를 들려주는 것이기도 하다고 하셨습니다. 추리소설이나 서스펜스 소설이 아닌 이야기도 많습니다. 논문은 소설이어서는 안 되고, 특히 서스펜스 소설이어서는 더더욱 안 됩니다.
요리책이나 튜토리얼, 레퍼런스를 읽으며 특정한 일을 해내려고 빠르게 익히는 중이라면 말씀에 전적으로 동의합니다. 물론 블로그 글로도 뭔가를 가르칠 수 있지만, 제가 블로그를 읽기로 했을 때는 필자의 개성을 조금 느끼고 그 과정에서 즐거움을 얻기를 바랍니다. 스토리텔링은 이 둘을 모두 잘 해냅니다. 또 블로그 글을 읽을 때는 서두르지 않고, 서둘러야 한다는 기분도 들고 싶지 않습니다.
좋은 글입니다. 블로그만이 아니라 모든 형태의 글로 하는 소통에 도움이 됩니다.
저는 연구자로 처음 일을 시작했을 때 한동안 훈련을 받아야 했습니다. 제 글쓰기는 좋지 않았어요. 영어는 네덜란드에서 고등학교를 다니며 배웠고 모국어 화자가 아닙니다. 그런데 모국어로도 글을 잘 쓰지는 못했습니다. 당시 석사 논문을 쓰고 있었고 박사 과정을 이어가기로 이미 정해 둔 상태였죠. 첫 번째로 출판될 논문도 같은 시기에 쓰고 있었습니다. 문체도 문법도 형편없었습니다. 문장이 서로 이어지지 않았고, 글 구조도 엉성했어요. 글쓰기를 직업적으로 해 본 적 없는 사람이 저지르는 초보 실수를 다 하고 있었습니다. 어떻게든 학회에 실리기는 했지만 썩 좋은 글은 아니었습니다.
당시 교수님께 받은 최고의 조언은, 체계적으로 틀리게 하는 일은 올바르게 하는 법도 배울 수 있다는 것이었습니다. 무엇을 잘못하고 있는지만 이해하면 된다고요. 교수님은 제가 뭘 어떻게 잘못하고 있고 왜 그런지 피드백을 아낌없이 주셨고, 저는 글쓰기가 빠르게 늘었습니다. 교수님은 저에게 매우 참을성 있게 대해 주셨지만, 이미 고쳐 주신 걸 또 틀리다 걸리면 달랐습니다. 몇 달이 지나자 제 실수 대부분을 제가 먼저 잡아내게 됐습니다. 그와 동시에 글을 검토하는 법도 익혔습니다. 제 글뿐 아니라 다른 사람들의 논문도 많이 검토했거든요. 제 글쓰기를 파악하려고 애쓰는 동안 좋은 논문과 나쁜 논문의 사례를 많이 접한 셈입니다.
또 하나 얻은 통찰은 글쓰기가 프로그래밍과 비슷하다는 점입니다. 아직 이야기하지 않은 것을 참조할 수는 없습니다. 내용을 제시하는 순서가 있고, 기대되는 구조가 있죠. 데드 코드 제거도 마찬가지입니다. 더는 쓸모없는 글은 지워야 합니다. 글은 논리적이고 자기완결적이어야 합니다. 결합도가 높으면 좋지 않고, 응집도가 낮아도 나쁩니다. 글을 단순하고 간결하게 유지하면서 자연스럽게 흐르게 하는 건 하나의 기예입니다. 같은 내용을 더 적은 단어로 말해 보라고 스스로에게 도전해 보세요. 단어 수나 쪽수 제한이 엄격할 때 아주 유용합니다.
"두서없는 서론"이 단연 가장 흔한 실수일지 몰라도, 가장 치명적인 실수는 단연 주제를 독자에게 익숙한 무언가와 연결하지 못하는 것(안티패턴 #2)입니다. 어떤 것은 이해를 시작하려면 일정 수준의 전문성이나 선행 지식이 필요하긴 합니다. 하지만 소프트웨어 블로그와 README 등에서 "이게 제가 아는 것과 비교하면 뭔가요? 제가 아는 관련 지식이 전혀 없다면 제가 왜 이걸 알고 싶어 해야 하나요?"라는 물음에 답하지 못하는 경우를 저는 거듭 봐 왔습니다.
이는 소프트웨어 분야의 거의 모든 것에 적용됩니다. 새로운 도구? 새로운 디자인 패턴? 새로운 라이브러리? 언어 관용구? 언어? 아니면 더 최신 사례로, 새로운 모델? 새로운 하네스? 새로운 하네스 옵션? 새로운 사용 패턴? 그게 없으면 프로젝트가 어떤 모습인지 간단히 요약해서, 그것의 존재만으로 풀리는 문제를 전달해 주세요. 그런 다음 다른 해결책들과 어떻게 비교되는지 자세히 들어가면 됩니다.
이런 정보를 직관적으로 느끼고 그게 없을 때 유독 짜증이 나는 건, 그냥 제 두뇌가 일하는 특유의 방식 때문일 수도 있겠습니다.
어떤 주는 제가 보는 소프트웨어 블로그 글 대부분이 이제 LLM이 쓴 것 같다는 생각이 들어요. 대개 형편없고요.
누가 LLM에게 이런 안티패턴을 알려 주면, 진지하게, 도움이 될까요?
물론 저는 사람들이 제가 읽기를 기대하는 글을 직접 쓰는 쪽이 좋습니다. 저는 인간이니까요.
따지고 보면 필자가 이 글을 온라인에 올린 것만으로 이미 알려 준 셈이죠.
지난주에 HN 링크를 따라갔다가 문득 기술 블로그에도 푸드 블로그 세계를 (좋은 쪽으로) 장악한 "Jump to Recipe" 링크가 필요해지기 시작했다는 생각이 들었습니다.