문서화를 안 하는 개발자에게

by 그릿 | GROWTH_ESSAY | 2026-06-26

#성장 #커리어

문서를 쓰라고 하면 싫다고 하는 개발자가 많습니다. 코드로 다 설명되는데 왜 또 써야 하냐고, 시간도 없는데 문서까지 챙기라는 거냐고 말합니다. 이 마음, 이해합니다.

그런데 멘토링을 하면서 문서화를 잘하는 개발자와 못하는 개발자의 커리어가 어떻게 갈리는지 오래 봐왔습니다. 그 차이가 생각보다 컸습니다.

코드는 읽히지만, 의도는 전달되지 않습니다

좋은 코드를 써도 다음 사람이 고생하는 경우가 있습니다. 왜 이렇게 설계했는지, 무슨 고민이 있었는지가 코드에는 없기 때문입니다. 그 고민은 코드를 작성한 사람 머릿속에만 있습니다.

그게 6개월 뒤의 본인이라도 마찬가지입니다. 반년 전에 내가 짠 코드를 보면서 "이게 뭐지?" 하고 헤맨 경험이 한 번쯤은 있을 겁니다.

시간이 없어서가 아닙니다. 정리가 안 돼서입니다.

문서로 쓰려면 생각이 정리되어 있어야 합니다. 흐릿하게 이해한 건 글로 못 씁니다. 그래서 문서를 안 쓰는 개발자 중 많은 수는 사실 본인이 뭘 했는지 제대로 정리되지 않은 상태입니다.

문서화는 작성 능력의 문제가 아닙니다. 사고 정리의 능력입니다.

이력서에 "문서화를 꼼꼼히 합니다"라고 쓴 사람을 저도 여럿 봤습니다. 그런데 정작 면접에서 "그 시스템을 다른 사람에게 설명해보세요"라고 하면 제대로 못하는 경우가 태반입니다.

반대로 문서화를 잘 하는 개발자는 다릅니다. 자기가 한 일을 짧고 명확하게 설명합니다. 전제를 이야기하고, 선택지를 이야기하고, 왜 그걸 골랐는지를 이야기합니다. 면접관이 원하는 게 사실 이겁니다.

매일 긴 문서를 쓸 필요는 없습니다. 오늘 한 작업 중 가장 헷갈렸던 것 하나만 짧게 적어보는 것부터 시작하면 됩니다.

"왜 이 방법을 택했는지", "다음에 이걸 다시 보는 사람에게 뭘 알려줘야 하는지"를 3줄로 적는 습관이 쌓이면 달라집니다. 글이 아니라 생각이 달라집니다.

그리고 그 생각의 차이가 나중에 커리어의 차이가 됩니다.