기술 문서는 가장 인간적인 글어야 한다

차가운 수치와 텍스트 사이에서 사용자에게 전달하는 배려

44 × 44 pt

아이폰 애플리케이션을 만들 때 권장하는 버튼의 크기이다. 버튼이나 아이콘 같은 터치 요소의 크기를 44×44 포인트 이상으로 만들 것을 권장한다. 이는 애플의 UI 설계 문서인 Apple Human Interface Guidelines에 등장하는 기준이다. 왜 꼭 44x44 pt로 만들라고 기준을 정한걸까? 33x33 pt도 있을 것이고, 55x55 pt도 있을 것이다. 그러나 이 가이드라인에서는 단순한 숫자만 가지고 얘기하지 않는다. 인터페이스가 움직임 또는 운동성이 제한된 사람들에게 편안한 경험을 제공하는지 확인하라고 제안한다.

이 편안한 경험을 제공하기 위한 버튼의 권장 크기가 44x44 pt이다. 정확히 말하면 사람의 손가락에서 나온 값이다. 사용자의 손가락은 마우스처럼 정확한 한 점을 클릭하지 않는다. 손가락은 생각보다 크고, 터치는 생각보다 부정확하다. 버튼이 너무 작으면 사용자는 다른 버튼을 잘못 누르거나 같은 동작을 여러 번 반복해야 한다. 이러한 부가 설명이 이 수치를 납득하게 만든다.

그런 관점에서 애플의 가이드라인과 기술문서들은 개발자와 사용자 입장에서 납득이 되는 문서이다. 개발자에게 단순히 버튼을 작게 만들어 화면을 깔끔하게 하라고 말하지 않는다. 대신 사용자가 실수 없이 누를 수 있도록 충분히 큰 터치 영역을 확보하라고 설명한다. 왜 그런 규격이 필요한지, 그 설계가 어떤 사용자 경험을 만들기 위한 것인지까지 설명한다.

흔히 기술 문서라고 하면 무미건조한 수식, 딱딱한 명령어, 끝없이 나열된 스펙 시트를 떠올린다. 하지만 가장 잘 쓰여진 기술 문서는 세상에서 가장 인간적인 글이다. 독자가 누구인지, 그가 어떤 상황에서 이 글을 읽을지, 그리고 어디에서 좌절할지를 치밀하게 계산하고 배려해야 한다.

먼저 기술문서는 누가 왜 읽는가를 이해해야 한다. 기술 문서를 찾는 사람은 대개 문제를 해결하고 싶어 하는 상태일 것이다. 대부분 처음 기기를 구매하거나 문제가 발생했을 때 설명서를 찾는다. 그 전에는 어디 있는지도 모르지만 언제나 기기 근처에 있다.

이 질문을 안고 들어온 독자에게 개발자의 복잡한 로직 설명은 소음일 뿐이다. 만약에 빨래건조기가 망가져서 작동하지 않는다. 그런데 기술설명서에서 이 세탁기의 개발 배경과 들어가 있는 부품 모두를 친절하게 설명하면 아마 분노에 차서 고객센터에 전화를 걸 것이다. 좋은 기술 문서는 독자의 지식 수준과 현재의 곤란함을 정확히 겨냥한다. 입문자에게는 친절한 지도가 되어주고, 전문가에게는 날카로운 레퍼런스가 되어준다. 건조기가 고장이 나서 "E60"의 메세지를 띄운다면, 다른 절차없이 E60에 대한 조치사항에 대해서 안내하면 된다. E60에 대한 자세한 설명은 후순위로 미루면 된다.

또한, 문장의 화려함보다 중요한 것은 명확한 목차와 설명이다. 목차를 훑는 것만으로도 해결의 실마리를 찾을 수 있게 만드는 구조화는 공학적 설계와 닮아 있다. 거창하게 말했지만, E60 에러메세지에 대한 부분을 빨리 찾을 수 있는 목차를 제시해야한다. 그리고 찾은 내용에서는 핵심 결론을 먼저 제시하고, 단계별 실행 방법을 나열하며, 발생 가능한 예외 상황을 미리 짚어주는 구성으로 내용을 작성해야 한다. 당신이 겪을 어려움을 우리는 이미 알고 있고, 여기에 해결방법이 있습니다라고 사용자에게 명확히 얘기해줘야 한다. 이것이 사용자의 화를 가라앉힐 수 있는 기본 문서구조이다.

실수하기 좋은 부분은 통보식의 내용을 작성하는 것이다. 단순히 A 버튼을 누르면 B가 작동한다는 매뉴얼은 반쪽짜리다. 진정으로 잘써진 기술 문서는 우리가 왜 이 방식을 선택했는지에 대한 설계 의도를 공유한다. 특정 수치를 결정한 배경 그리고 이 기술이 지향하는 가치까지 기록하는 것이다. 이 맥락이 공유되면 이 A 버튼을 누르는 일에 다른 이견을 갖지 않는다.

그리고 설명은 언제나 정확하게 전달해야 한다. 이 점을 극적으로 보여주는 사건도 있다. 화성 탐사선 Mars Climate Orbiter가 궤도 진입 과정에서 소실된 사고다. 처음에는 복잡한 기술적 결함이 원인일 것이라 예상됐다. 그러나 문제는 기술문서였다. 한 팀은 추진력 데이터를 파운드힘 단위로 계산했고, 다른 팀은 뉴턴 단위로 계산하고 있었다. 이 공유된 기술문서에서 어떤 단위를 사용하는지 명확하게 전달되지 않았기 때문이다. 결국 탐사선은 예상보다 낮은 고도로 진입했고 화성 대기권에 들어가면서 파괴됐다. 설명이 정확하지 않았기 때문에 기술 전체가 실패한 사건이다.

그래서 공학자에게 기술 문서를 쓰는 일은 개발이 끝난 후 숙제처럼 처리하는 부차적인 업무가 아니다. 문서는 사용자가 기술과 만나는 가장 직접적인 인터페이스다. 아무리 훌륭한 엔진을 가졌어도 조작법을 모르면 무용지물이다. 결국 훌륭한 기술은 훌륭한 기술 문서를 통해 사용자에게 기술서비스를 제공한다.

결국 기술 문서를 쓴다는 것은 내가 만든 기술을 사용하는 타인의 수고를 덜어주려는 다정함이 밑바탕이 되어야 한다. 냉정하고 차가운 수치와 텍스트 사이에서 사용자에게 전달하는 배려가 느껴질 때, 기술 문서는 단순한 설명서를 넘어 인간과 기술을 잇는 가장 따뜻한 가교제 역할을 한다.