기술 블로그의 안티패턴 6가지와 이를 극복하는 방법들

diary

2 분 읽기

내 블로그의 글은 좋은 글일까? 독자들이 읽기 편한 글일까? 이러한 고민에 도움이 될 만한 글을 만났다.
(Anti-Patterns in software blogging)

이번 포스팅에서는 원문에서 소개하는 기술 블로그의 여섯 가지 안티 패턴을 번역하고, 핵심을 추출/요약하여 정리해 보겠다.

글을 열심히 쓰는 것만큼, 잘 전달하는 방법도 고민하는 분들에게 도움이 되길 바란다.

안티패턴이란
소프트웨어 개발에서 문제가 되는 전형적인 구현 방식을 이르는 말

1. 장황하고 갈피를 못잡는 도입부

  • 도입부에서 배경 설명, 맥락 설명에 너무 많은 분량을 할애하면 독자들은 결론에 도달하기 전에 이탈함
  • 이를 막기 위해 아래 두 가지를 제목과 첫 3문장 이내에서 제시해야 함
  • (1) 이 글이 누구를 위한 글인지
  • (2) 이 글을 읽었을 때 얻을 수 있는 게 무엇인지
1
2

제목 : 더 나은 Go 테스트 코드를 작성하는 방법  
도입 : 많은 개발자들이 모르는 유용한 Go 테스트 패턴이 있습니다. 30초만에 핵심을 알려드리겠습니다.

2. 독자는 내가 아는 모든 것을 알지만, 단 한가지만 모른다는 착각

  • 독자들이 나와 같은 배경지식을 가지고 있다고 생각하는 것은 착각임
  • 어떤 개념을 설명할 때, 독자에게 익숙한 것에 비교하는 게 좋음. 중요한 건 독자에게 익숙한 것이 무엇인지 정확하게 파악하는 것
  • (1) 글을 작성할 때에는 목표 독자를 구체적으로 설정해야 한다.
  • (2) 주변 동료나 친구 중 한 사람을 떠올려보고, 그 사람이 알 만한 용어와 모를 만한 용어의 기준을 세워보자
1
2
3
4
5

나쁜 예시 : 독자가 나와 같은 배경지식을 가지고 있을 거라고 가정하는 서술

이번 글에서는 Docker를 처음 접하는 분들을 위해 Docker를 소개합니다.  
Docker는 간단합니다. 리눅스 cgroups의 깔끔한 프론트엔드에 불과합니다.  
혹시 FreeBSD의 jail을 아시나요? Docker는 그것의 리눅스 버전입니다.  

1
2
3
4
5
6
7
8

좋은 예시 : 독자의 배경지식에 대한 가정을 최소화하는 서술  

Redis는 데이터를 메모리에 올려 빠르게 저장하고 조회할 수 있도록 도와주는 데이터 저장소입니다.  
일반적인 데이터베이스가 데이터를 디스크에 쓰는 것과 달리,
Redis는 데이터를 메모리에 올려둠으로써 빠르게 접근할 수 있게 해줍니다.  
예를 들어 자주 사용하는 사무 용품을 저 멀리 있는 창고에 두는 것보다, 책상 위에 보관하두는 게 나은 것과 같습니다.  
자주 사용되는 데이터에 대해 가까운 곳에 임시로 저장해두는 이러한 방식을 캐싱이라고 합니다.
Redis는 이러한 캐싱을 구현하는 데 널리 활용됩니다.

3. 하이퍼링크에 대한 과도한 의존

  • 개념을 설명하기 귀찮아 하이퍼링크로 대체하는 경우가 많이 보임
  • 하지만 생각해보라. 책을 읽다가, 거기 나오는 개념을 이해하기 위해 다른 책을 보고 와야 하는 상황을.
  • 이러한 흐름이 끊기는 상황을 경계해야 한다.
  • (1) 링크는 글을 깊이 이해하기 위한 “보너스”여야지, “필수 선행 조건”이 되면 안된다.
  • (2) 링크를 건다면, 걸되 핵심 내용은 본문에 직접 요약해 독자를 내 페이지에 머물도록 해야 한다.

4. 속편 주입 버그

  • 최근 블로그글에서 영화처럼 후속편을 다루는 형태의 글이 자주 있음 (뜨끔)

지난 1편에서는 … 오늘은 1편에서 소개했던 개념을 바탕으로 …

  • 대부분의 독자들은 1편을 읽지 않은 상태로 유입됨
  • 지난 글을 독자들이 읽었을 것이라고 전제한다면, 독자들은 이전 글까지 찾아 읽어야 한다는 피로감을 느낄 것
  • (1) 이전 글을 언급해야 한다면, 서두에서부터 언급해서는 안됨
  • (2) 과거 글을 인용할 때에는 독자가 해당 글을 전체 다 읽지 않아도 맥락을 이해할 수 있도록 필요한 내용을 간략히 요약해줘야 함

5. 지나친 격식 차리기

  • 초보 블로거들은 글이 전문적으로 보이기 위해 딱딱하고 격식있는 문체를 써야 한다는 강박이 있음
  • 기술 블로그는 보고서가 아님. 개발은 격식에 얽매이지 않는 직군 중 하나임
  • (1) 글을 읽는 독자는 편한 옷차림으로 모니터 앞에서 시리얼을 먹고 있는 독자일 가능성이 높음. 딱딱한 문체를 원하는 독자는 없음
  • (2) 실제 대화하듯, 편하게, 자연스럽게 쓰면 됨

최근 많은 개발자가 글 작성을 AI에 의존하면서 기술 블로그들이 점차 무미건조해지고 개성을 잃고 있음
하지만 기억해야한다 : 독자들은 저자의 개성이 묻어나는 글을 원한다.
편안하고, 솔직 담백하며, 마치 점심시간에 동료에게 이야기하듯이 써내려가는 글을 원한다.

6. 기본적인 랜더링 실수

  • 모바일 독자들이 적지 않다는 점을 간과하지 말아야 한다.
  • 모바일 독자들에게 최악의 경험은 텍스트나 이미지가 화면 너비를 벗어나 좌우 스크롤을 해야만 하는 경우
  • (1) 따라서 레이아웃이 깨지지는 않는지 반드시 확인할 것
  • (2) 그리고 가독성 좋은 폰트와 배치를 쓸 것

Reference

https://refactoringenglish.com/blog/anti-patterns-software-blogging/

// reading compass

이 글과 이어지는 경로

시리즈, 카테고리, 태그 겹침, 최신도를 점수화해 가까운 글일수록 중심에 배치합니다.

hover nodes or cards · click a node to pin
Next reads 0

    댓글 남기기

    이런 글은 어떠세요