기술을 이해하는 데에는 그 기술의 동기가 중요하다. 정확히는, 그 기술을 이상하게
오용하지 않기 위해서는 동기를 이해해야 한다.
이상적으로는 기술을 이해하는 데에도 기술의 역사에 대한 지식이 동반되어야 하겠지만, 현실적으로는 우리에게는 그러한 것까지 일일히 기억할 만큼의 여유가 없다. 우리가 습득해야 하는 기술은 일터에서 허겁지겁 주워삼키는 것들이다.
기술 문서를 쓸 때도 이와 같은 갈등에 놓인다. 대여섯 문단을 할애하여 이 기술의 배경에 대해 다룰 것인가? 아니면 와닿지 않는 한 문장으로 동기에 대한 설명을 퉁치고, 곧바로 기술의 작동 방식에 대한 서술로 넘어갈 것인가?
기술 문서를 읽는 입장에서 보자면, 기술의 배경에 대해 길게 서술한 내용은 내가 그 기술에 개인적인 관심을 두고 있지 않은 이상, 그러니까 당장 오늘 저녁까지 어떤 것을 구현해내기 위한 과정으로 문서를 읽고 있는 경우, 잘 눈에 들어오지 않는다. 허겁지겁
주워삼킨다는 것은 이런 뜻이다. 복사해서 붙여넣을 예제 코드가 필요하다.
여러 해 기술 문서를 쓰는 것에 대해 고민해왔는데, 그래서 이 문제에 대한 해결책을 찾았냐고 하면 여전히 해결책이 묘연한 상태다. 다만 한가지 노하우는 공유할 수 있을 것 같다.
기술 문서를 자랑 내지는 광고를 한다는 태도로 쓰면 좋다. 문서를 어떤 방향으로 작성해야 할지 실마리가 잘 풀린다. 어떤 내용이 필요 없는지도 비교적 잘 보인다. 다만, 애초에 자랑이나 광고를 할 마음이 들지 않을 수도 있다. 그렇다면 그 기술의 가치에 대해 고민해볼 필요가 있다. 그런 마음이 든다고 해서 항상 가치가 없다는 얘기는 아니지만, 정말 가치가 없어서 그런 생각이 들 때도 분명 있기 때문이다.