개발자는 글을 못쓴다고요 서평

2026. 2. 4. 17:21ㆍ서평

『개발자는 글을 못 쓴다고요?』 서평

기본 정보

제목: 개발자는 글을 못 쓴다고요?
저자: 전정은, 황수정
출판사: 제이펍
읽은 기간: 2025년 12월 3일 ~ 12월 17일

읽게 된 이유

프로젝트를 진행할 때 기능 구현은 어떻게든 해내지만, 문서화는 늘 뒤로 밀리는 편이었다. README는 비어 있거나 최소한의 실행 방법만 남아 있고, 변경사항은 머릿속에만 남아 시간이 지나면 "왜 이렇게 설계했지?"부터 다시 떠올려야 했다. 회고 글도 '잘 써야 한다'는 부담 때문에 시작이 늦어지기 일쑤였다.

이 책은 제목 자체가 내 상황을 정확히 찌르는 느낌이었다. 개발자가 글을 "잘 쓰는 사람"이 되는 게 목표라기보다, 적어도 내가 했던 일을 나중에 다시 꺼내 쓸 수 있게 기록하고 싶었다. 그 방법을 구조적으로 배우고 싶어서 읽게 되었다.

💡 전반적인 느낌

다양한 예시가 준 안정감

이 책은 원론적인 조언보다 개발자가 실제로 마주치는 문서·공유·설명·기록 상황을 기준으로 예시를 제시한다. 그래서 읽는 내내 "이건 내 프로젝트에 바로 적용할 수 있겠다"는 감각이 들었다. 막연한 동기부여가 아니라, 바로 손이 움직이게 만드는 안내서에 가까웠다.

친절한 설명 덕분에 시작 장벽이 낮아졌다

글쓰기가 어려운 이유는 문장력 부족이 아니라, 어디서부터 무엇을 어떤 순서로 써야 하는지 보이지 않기 때문이다. 이 책은 그 시작점을 구조로 잡아준다. 멋진 글보다 읽는 사람이 정보를 빠르게 찾도록 만드는 구성이 먼저라는 관점이 특히 실용적이었다.

🎯 내가 가져간 핵심 메시지

책을 읽고 정리한 핵심은 다음과 같다.

개발자 글쓰기의 목적은 감동이 아니라 전달과 재사용이다
글은 센스보다 형식과 습관으로 좋아진다
문서화는 "추가 업무"가 아니라, 다음 작업을 쉽게 만드는 미래 비용 절감이다
잘 쓰려고 멈추는 것보다, 일단 쓰고 다듬는 방식이 현실적이다

결국 글을 잘 쓰는 사람이 되기 전에, 기록을 끊지 않는 사람이 되는 게 먼저라는 결론이었다.

적용해볼 것

읽고 끝내지 않기 위해, 당장 프로젝트에 붙일 수 있는 방식으로 적용 항목을 정리해두었다.

1) 체인지로그는 "공식 문서처럼" 쓴다

체인지로그에는 반드시 버전, 날짜, 신규 기능, 변경 기능, 수정(버그), 삭제 기능, 호환성 이슈가 들어가야 한다. 무엇보다 중요한 기준은, 최종 사용자에게 영향이 없어도 변경 사실은 기록에 포함시키는 것이다. 내부 리팩토링, 설정 변경, 의존성 업데이트 같은 작업도 나중에 회귀 이슈를 추적할 때 결정적인 단서가 되기 때문이다.

체인지로그는 감상이나 맥락 설명을 길게 붙이기보다, 공식 문서처럼 무미건조하게 변경 사실을 나열하는 방식이 더 맞다. 핵심만 간결하게 적되, 누락 없이 남기는 것이 목표다.

내가 쓰려는 템플릿:

## v1.3.0 (2025-12-17)

### Added (신규 기능)
- 관리자 검색 필터 추가

### Changed (변경 기능)
- 정렬 기준 기본값 변경

### Fixed (수정/버그)
- 특정 조건에서 목록이 비어 보이던 버그 수정

### Removed (삭제 기능)
- 사용되지 않는 레거시 옵션 제거

### Compatibility (호환성 이슈)
- 환경변수 이름 변경으로 배포 설정 수정 필요

2) README는 순서를 고정한다

README를 "소개 글"이 아니라, 처음 보는 사람이 빠르게 실행하고 이해하도록 돕는 사용 설명서로 정의한다. 앞으로는 README를 아래 순서로 고정해 작성하려 한다.

간략한 소개: 무엇을 해결하는지 한 문장 + 핵심 기능
사용 준비: 설치 방법, 요구 버전, 환경변수, 실행 전 체크사항
사용 방법: 기본 사용 흐름(가장 흔한 시나리오부터)
예시 코드: 복붙 가능한 최소 예제(1~2개), 입력/출력까지 포함

순서를 고정하면 "잘 쓰려다 멈추는" 일이 줄고, 프로젝트가 커져도 README가 일관된 형식으로 유지될 가능성이 높아진다.

3) 블로그 글에는 "읽는 시간"을 표시한다

앞으로 블로그 글 상단에 예상 읽는 시간(Reading time)을 넣으려 한다. 독자는 글을 클릭하기 전에 소요 시간을 알면 부담이 줄고, 소비 여부를 빠르게 판단할 수 있다. 글이 짧든 길든 "몇 분이면 읽는지"를 명확히 보여주는 것이 사용자 친화적이다.

4) 내용 아이디어는 마인드맵으로 먼저 그린다

글을 쓰기 어려운 가장 큰 이유는 문장력이 아니라, 구조가 머릿속에서 정리되지 않았기 때문인 경우가 많다. 그래서 글을 쓰기 전에 먼저 주제와 하위 내용을 마인드맵으로 빠르게 펼쳐 흐름을 만든 뒤, 그 구조를 목차로 변환해 작성하려 한다.

특히 "핵심 메시지 → 근거/예시 → 적용 계획 → 마무리" 순서로 가지를 뻗으면 글이 산으로 가지 않고, 처음부터 끝까지 논리 흐름이 유지된다.

마무리

개인 소감

이 책을 읽으면서 가장 크게 와닿았던 건, 글쓰기의 핵심은 "잘 쓰기"가 아니라 "일단 남기기"라는 점이었다. 과거 프로젝트의 의사결정 과정이나 트러블슈팅 경험을 떠올리려 하면 잘 기억나지 않는 경우가 많았다. 당시엔 분명 고민하고 해결했던 문제들인데, 기록이 없으니 머릿속에서 흐릿하게 사라져버린 것이다.

이제는 완벽한 문서를 만들려다 시작조차 못 하는 대신, 작은 메모라도 남기는 것부터 시작하려 한다. 체인지로그 한 줄, 커밋 메시지 한 문장이라도 명확하게 쓰는 습관이 쌓이면, 나중에 그것들이 나를 설명하는 든든한 기록이 될 거라 믿는다. 결국 기록은 미래의 나를 위한 가장 확실한 투자다.

호조리카