[책] Docs for Developers

Docs for Developers

한빛미디어에서 개발 생태계에 모든 사람을 위한 기술 문서 작성 방법을 설명하는 Docs for Developers가 발간 됐습니다. 무릇 개발자라면 코드만 작성하는 것이 아니라 문서 작성도 해야 합니다. 본인이 개발한 코드를 설명하는 문서 혹은 릴리스 문서 등을 포함해서 말이죠. 그리고 글이 더 잘 소비되도록 문단 하나까지도 신경을 쓸 겁니다.

이미지를 하나씩 제공하면 인지 처리가 덜 필요하고, 두뇌가 연결 관계를 도출하는 데 도움이 되며, 텍스트보다 훨씬 빨리 이해를 이끌어 냅니다. 또한 우리는 정보가 이미지와 함께 제공되면 정보를 더 잘 기억합니다. 정보를 귀로 듣는 경우에는 약 10%만 기억합니다. 그러나 정보를 들을 때 이미지가 함께 나온다면 65%를 기억할 수 있습니다.

그동안 나름 양질의 문서를 작성해 왔다고 생각했는데요. 이 책을 통해 근본 있게 문서를 작성하는 법을 조금은 배운 것 같습니다. 특히 부록에 담겨있는 테크니컬 라이터의 인터뷰를 통해 해당 직군을 이해할 수 있었고 좋은 글쓰기를 위한 방법, 길을 어느 정도 알게 된 것 같습니다. 기술 블로그를 포함해서 문서화에 대해 고민하시는 분께 일독을 권합니다.

아, 책 중간에 “지식의 저주”를 만나서 얼마나 반가웠는지 모릅니다.

"1980년대 후반, 하버드 대학의 한 경제학자 그룹은 사람들이 다른 사람도 자신과 같은 지식을 갖고 있다고 가정한다는 연구 결과를 내놓았습니다. 그들은 이 인지적 편향을 '지식의 저주(curse of knowledge)라고 명명했습니다. 몇 년 후, 스탠퍼드 대학의 한 박사 과정 학생이 지식의 저주를 실험으로 보여주었습니다. 그녀는 실험 참가자를 두 그룹으로 나눈 후, 한 그룹에게는 잘 알려진 노래의 리듬에 맞춰 손가락을 두드리라도 하고 다른 그룹에게는 두드리는 소리를 듣고 어떤 곡인지 맞춰 보라고 했습니다. 두드리는 쪽에서는 노래를 생생히 떠올리고 있으므로 듣는 쪽이 대부분의 노래를 알아맞힐 수 있을 거라고 생각했습니다. 하지만 결과는 그렇지 않았습니다. 두드리는 쪽은 듣는 쪽이 51%의 확률로 노래를 예측할 것이라고 생각했지만, 안타깝게도 듣는 쪽에서는 겨우 2.5%의 확률로 노래를 맞췄습니다

실제로 회사에서 세션을 발표할 때 마이크를 두드려서 "작은별"을 연주했지만 맞춘 사람은 2%도 안됐습니다. 사람들은 본인이 알고 있는 걸 남도 비슷한 수준으로 알 것이라고 착각한다는거죠. 이걸 제가 직접 테스트해 본 이후로는 누군가에게 뭔가 설명하는 방식을 많이 바꿨습니다. 그리고 설명을 요청할 때도 “개발자를 넘어 기술 리더로 가는 길”의 저자가 이야기하는 것처럼 ELI5(Explain it like I’m 5 years old)로 히는 걸 좋아합니다. 여러분도 꼭 한 번 해보시길 바랍니다.