개발자 블로그가 독자를 놓치는 가장 흔한 실수
Anti-Patterns in Software Blogging
소프트웨어 블로깅에서 흔한 안티패턴을 정리했다. 가장 큰 문제는 서론이 길어지는 것. 독자는 제목과 첫 세 문장 안에 '내가 읽을 이유'를 찾지 못하면 떠난다. 독자가 아는 것을 과대평가하거나, 모르는 용어를 링크로 때우는 것도 금물. 링크는 보너스일 뿐, 읽는 흐름을 끊으면 안 된다. 전편을 읽었다고 가정하는 '속편 주입 버그'와 지나친 격식체도 피하라. 모바일에서 화면이 넘치거나 저대비 폰트로 읽기 어렵게 만드는 기본적인 실수도 꼽혔다.
당신은 1988년 IBM의 80세 임원을 위해 글을 쓰는 게 아니다. 당신의 분야는 소프트웨어 개발이며, 가장 가식 없는 화이트칼라 직업 중 하나다. 당신의 글을 읽는 사람은 아마 잠옷과 슬리퍼 차림으로 키보드 옆에서 시리얼을 먹고 있을 것이다.
HN 토론
102- phreack
저는 교육은 스토리텔링이 아니며 그렇게 구성되어서도 안 된다고 늘 주장합니다. 사람들은 '반전'과 '깨달음'을 최대 임팩트를 위해 아껴두고 싶어 하는데, 이는 해롭습니다. 사실은 정반대여야 하고, 주제를 유지하자면 '스포일러' 같고 반복적이어야 합니다. 좋은 발표처럼, 무엇을 말할지 먼저 말하고, 말한 다음, 마지막에 말한 것을 요약해야 합니다.
LLM 때문에 이 문제가 극도로 심해졌습니다. MCP가 무엇인지 몇 마디로 기술적으로 설명한다고 상상한 뒤, 검색해 보세요. 전화번호부만큼의 페이지와 끝없는 텍스트가 있는데 결코 요점에 도달하지 않습니다.
- jrochkind1
몇 주 동안은 제가 보는 소프트웨어 블로그 대부분이 이제 LLM이 쓴 것 같다는 느낌이 듭니다. 그것들은 대개 형편없습니다.
누군가 LLM에게 이런 안티패턴들을 알려줄 수 있을까요? 진심으로, 도움이 될까요?
물론 저는 사람들이 제 인간인 제가 읽기를 기대하는 텍스트를 실제로 직접 쓰기를 더 선호합니다.
- ram1500natrluvr
'두서없는 도입부'가 단연 가장 흔한 실수일 수 있지만, 단연 가장 해로운 실수는 주제를 독자가 익숙한 무언가와 연결하지 못하는 것(안티패턴 #2)입니다. 어떤 것들은 이해를 시작하려면 일정 수준의 전문성/선수 지식이 필요하지만, 소프트웨어 블로그, README 등에서 '이것은 무엇이고, 내가 익숙한 것과 비교하면 어떤 것이며, 내가 관련해 익숙한 게 없다면 왜 익숙해지고 싶어 해야 하는가?'에 답하지 못하는 경우를 반복해서 봤습니다.
이는 소프트웨어 영역의 거의 모든 것에 적용됩니다. 새 도구? 새 디자인 패턴? 새 라이브러리? 언어 관용구? 언어? 또는 더 현대적인 관점에서는 새 모델? 새 하네스? 새 하네스 옵션? 새 사용 패턴? 그것 없이 프로젝트가 어떤 모습인지 간략히 요약해서, 그것의 존재 자체가 해결하는 문제를 전달하세요. 그런 다음 다른 해결책과 어떻게 비교될 수 있는지 세부 사항으로 들어가세요.
어쩌면 이런 종류의 정보를 직관적으로 느끼고 그것의 부재를 특히 짜증나게 여기는 건 제 뇌가 작동하는 특정 방식일 수도 있습니다.
- CM30
튜토리얼, 비디오 게임 공략, 레시피 등을 쓸 때 맞닥뜨리게 될 단연 가장 큰 도전은 이것입니다:
> "독자는 내가 아는 모든 것을 알고 있지만, 이 한 가지만 모른다"
기사에서 말하듯이, 독자가 이미 무엇을 아는지 알기 어렵고, 도와주려 할 때 자신이 근육 기억에 맡긴 것들이 얼마나 많은지 잊어버려 '지름길'을 택하기 너무 쉽기 때문입니다.
사람을 가르치는 건 어렵고, 조심하지 않으면 정말 많은 결정적 정보를 빼먹기 쉽습니다.
그렇긴 해도, 여기서 고려할 만한 안티패턴 하나(그리고 권장 디자인 패턴 하나)가 더 있습니다.
안티패턴은, 해당 주제의 업데이트 때문에 튜토리얼이 더 이상 작동하지 않는 경우입니다. 몇 년 전 Angular를 배우려 할 때 이게 큰 문제였던 기억이 납니다. 공식 튜토리얼이 분명히 현재와 매우 다르게 작동했던 오래된 버전의 프레임워크를 위해 쓰였기 때문입니다.
온라인에서 그런 문제를 겪은 횟수가 너무 많고, 보통은 언어, 프레임워크 또는 관련 의존성이 큰 업데이트를 할 때마다 튜토리얼을 쓴 사람이 다시 확인하지 않았기 때문입니다.
그러니 어떤 주제에 대해 쓰고 상황이 크게 변했다면, 돌아가서 이전 작업을 확인하세요. 가능하면 글을 업데이트하고, 안 되면 최소한 글 상단에 이제는 구식이니 건너뛰어야 한다는 공지를 넣으세요.
다른 얘기로, 염두에 둘 좋은 패턴은 […]
- janalsncm
이 모든 것은 결국 공감으로 귀결된다고 말하고 싶습니다. 목표 독자가 누구인지 생각하고, 그중 가장 정보가 적은 사람을 위해 쓰세요.
목표 독자를 선별하는 건 괜찮습니다. 우리 대부분은 어차피 무료로 쓰고 있으니, LLM 처리량 최적화에 관한 글에서 컴퓨터가 무엇인지 설명하지 않는다고 수익이 줄지 않습니다. 여러분은 주제에는 익숙하지만 여러분 프로젝트의 세부 사항에는 익숙하지 않은 다른 엔지니어에게 쓰고 있을 수 있습니다.
가장 중요한 것을 상단에 배치하세요. 첫 10초 안에 누군가의 관심을 끌면, 30초를 더 벌 수 있습니다.
시각 자료를 추가하세요. 상자와 화살표, 차트, 적절한 곳에는 비디오도요.
꼭 두서없는 서사를 써야 한다면, 시작이 아니라 끝에 두세요.
- linsomniac
지난주에 HN 링크를 따라가다가, 기술 블로그에도 음식 블로그 세계를 (더 나은 쪽으로) 장악한 그 '레시피로 건너뛰기' 링크가 필요해지기 시작했다는 생각이 들었습니다.
- weinzierl
"두서없는 도입부"
도입부만 그런 게 아닙니다. 많은 블로거가 마치 이야기를 쓰듯, 서스펜스를 쌓는 등으로 쓰려고 합니다. 기술 글쓰기에서는 요점을 묻어두지 마세요.
- zrail
"이건 하고 저건 하지 마라" 목록은 항상 맥락과 상황에 따라 달라집니다. 일부는 전문직 또는 비즈니스 사이트의 맥락에서는 말이 되지만, 조언을 받아들이기 전에 자신의 목표와 일치하는지 확인하세요.
개인 블로그에 쓰고 있다면, 이 모든 것을 스스로 느끼는 만큼의 소금 결정 크기로 받아들이세요. 개인적으로는 절벽 위에 매달려 방심한 리스티클 작가^h^h코요테를 기다리는 Acme 금고 정도의 크기입니다.