2021.07.27

“좋은 문서 없으면 좋은 코드도 없어” 테크니컬 라이터의 중요성

Matt Asay | InfoWorld
소프트웨어가 중요할까, 아니면 소프트웨어를 더욱 잘 사용할 수 있게 설명하는 문서화가 더 중요할까? 경력과 지리적 조건이 비슷하다면 아마도 두 직업 모두 중요도가 비슷하다고 추정하는 것이 타당할 것이다. 그러나 올바른 판단은 아니다. 소프트웨어 개발자는 백만장자는 아니지만, 코드를 유용성과 배경을 설명하는 직업인 테크니컬 라이터보다 훨씬 수입이 높다.

이러한 관행에 제동을 걸 때다. 흐릿한 공정성을 논할 일이 아니다. 테크니컬 라이터가 만들고 잠금을 푸는 작업의 가치를 깨닫는다면 아마도 조직도 이들의 연봉을 올리고 싶어질 것이다.
 

모래에서 금가루 걸러내기

엔보이 프로젝트 창립자이자 리프트에서 개발자 부서를 운영하는 맷 클라인은 훌륭한 개발자의 가치를 잘 알고 있다. 클라인은 같은 이유로 훌륭한 테크니컬 라이터에 훨씬 더 큰 중요성을 부여한다. “훌륭한 테크니컬 라이터를 찾는 것은 훌륭한 개발자보다 100배는 어렵다. 이들의 연봉은 개발자보다 높아야 한다.”

핵심은 연봉이 같은 수준을 넘어 훨씬 더 높아야 한다는 주장이다.
 
ⓒ Getty Images Bank

셰프의 제품 관리자 팀 스미스는 그 이유에 대해 “아무도 사용법을 모르는 기술이라면 무엇을 개발하든 전혀 의미가 없다”고 설명했다. 개발자들도 여기에 동의하면서 문서화를 개발자 생산성을 향상하는 가장 우선적 요구사항으로 꼽는다. 휴먼 시큐리티의 비던 노블은 문서를 가리켜 “제품의 가장 근본이 된다”고 설명했다. 좋은 문서가 없다면 코드를 내보낼 수 없다.

개발자들도 할 말이 많다. 오픈소스 프로젝트와 문서화의 관계에 대한 깃허브 설문조사에 응답한 개발자의 93%가 불완전하거나 명확하지 않은 문서화에 불만이 많았다. 상용 소프트웨어의 상황은 훨씬 낫다. 테크니컬 라이터들이 훨씬 나은 대우를 받기 때문이다. 그런데도 연봉이 충분하지 않다는 문제는 남아 있다.

IT 분야 구직구인 전문 업체 인디드(Indeed)의 연봉 데이터에 따르면 미국 소프트웨어 엔지니어의 평균 기본급은 10만 4,000달러다. 라이트더닥(WriteTheDocs)이 2020년 연봉 관련 설문 조사에서 발표한 미국 테크니컬 라이터 연봉과 크게 다르지 않다. 그러나 평균의 오류에서 벗어나면 상황이 달라진다. 상위에 랭크된 소프트웨어 개발자들의 연봉은 10만 달러를 훨씬 넘기 때문이다. 그러나 상위 25% 테크니컬 라이터의 연봉은 그렇지 않다.

데이터스택스(Datastax)의 CSO 샘 램지와의 대화에 따르면 구글 테크니컬 라이터 패트리샤 보스웰은 훌륭한 코드는 훌륭한 이야기가 필요하다고 강조한다. 대부분의 기술 청중이 이해할 수 있어야 한다는 것이다. 램지는 “주제가 얼마나 기술적인지와 상관 없이, 기본 뼈대는 언제나 좋은 이야기여야 한다”고 주장했다. 램지는 과거 한때 코드는 해독하기 어려웠고 아주 드문 것이었다고 설명한다. 그러나 지금 코드는 그야말로 “넘쳐난다.” 부족한 것은 “누군가가 이미 알고 있는 것과 이미 하고 있는 것을 멈추고 개발자나 기술 청중이 충분히 확인하고 즐길 수 있는, 설득력 있는 이야기”다. 램지는 “그 이야기를 사용해 지역 사회의 일원이 되기 위해 역량을 개발할 수 있어야 한다”고 강조했다.

이때 필요한 것이 바로 좋은 문서다. 좋은 코드의 개발 과정에는 좋은 문서가 필요하다.

코드가 아니라 문서가 주요 인터페이스가 될 경우에 문서는 훨씬 중요하다. 예를 들어 API 기저의 코드를 작업할 경우를 말한다. 그러나 보스웰이 강조한 것처럼 훌륭한 테크니컬 라이터는 단순히 자신이 소프트웨어가 어떻게 작동하기를 바라는지를 기술하는 사람이 아니다. 오히려 훌륭한 테크니컬 라이터는 소프트웨어의 과거 사용 방식을 잘 기술하는 사람이어야 한다. 보스웰은 “그러기 위해서는 시야에 보이는 모든 조각을 한데 묶을 수 있어야 한다. 마케팅 목표, 기능적 목표, 사용자 경험을 하나로 연결하는 완성된 내러티브를 만들어내는 것이다. 테크니컬 라이터는 UX와 협력해 경험을 문서화한다. 여기에서부터 모든 것이 흘러나온다”고 설명했다.

이 능력의 가치가 높다고 생각한다면 아마도 그것이 사실이기 때문일 것이다. 훌륭한 테크니컬 라이터는 왜 이 소프트웨어를 사용해야 하는지 다른 이를 설득하는 것은 물론이고, 미래의 필수 사용자 역시 같은 내러티브 안에서 소프트웨어를 사용하는 방법을 선명하게 그릴 수 있도록 돕는 역할을 한다. 물론 여기에도 전략적 구성 요소가 있지만 테크니컬 라이터의 작업은 매우 전략적인 역할이다.

클라인에 따르면 테크니컬 라이터는 외부에서 가져다 쓰기 어려운 직업이기도 하다. 즉, 훌륭한 테크니컬 라이터를 원하는 조직은 그에 상응하는 비용을 지불할 준비가 되어 있어야 한다. 가장 우수한 개발자보다 더 많은 비용이 들지도 모른다. 개발자만큼이나 우수한 테크니컬 라이터가 없으면 훌륭한 개발자도 빛을 발하지 못할 것이기 때문이다. editor@itworld.co.kr 


2021.07.27

“좋은 문서 없으면 좋은 코드도 없어” 테크니컬 라이터의 중요성

Matt Asay | InfoWorld
소프트웨어가 중요할까, 아니면 소프트웨어를 더욱 잘 사용할 수 있게 설명하는 문서화가 더 중요할까? 경력과 지리적 조건이 비슷하다면 아마도 두 직업 모두 중요도가 비슷하다고 추정하는 것이 타당할 것이다. 그러나 올바른 판단은 아니다. 소프트웨어 개발자는 백만장자는 아니지만, 코드를 유용성과 배경을 설명하는 직업인 테크니컬 라이터보다 훨씬 수입이 높다.

이러한 관행에 제동을 걸 때다. 흐릿한 공정성을 논할 일이 아니다. 테크니컬 라이터가 만들고 잠금을 푸는 작업의 가치를 깨닫는다면 아마도 조직도 이들의 연봉을 올리고 싶어질 것이다.
 

모래에서 금가루 걸러내기

엔보이 프로젝트 창립자이자 리프트에서 개발자 부서를 운영하는 맷 클라인은 훌륭한 개발자의 가치를 잘 알고 있다. 클라인은 같은 이유로 훌륭한 테크니컬 라이터에 훨씬 더 큰 중요성을 부여한다. “훌륭한 테크니컬 라이터를 찾는 것은 훌륭한 개발자보다 100배는 어렵다. 이들의 연봉은 개발자보다 높아야 한다.”

핵심은 연봉이 같은 수준을 넘어 훨씬 더 높아야 한다는 주장이다.
 
ⓒ Getty Images Bank

셰프의 제품 관리자 팀 스미스는 그 이유에 대해 “아무도 사용법을 모르는 기술이라면 무엇을 개발하든 전혀 의미가 없다”고 설명했다. 개발자들도 여기에 동의하면서 문서화를 개발자 생산성을 향상하는 가장 우선적 요구사항으로 꼽는다. 휴먼 시큐리티의 비던 노블은 문서를 가리켜 “제품의 가장 근본이 된다”고 설명했다. 좋은 문서가 없다면 코드를 내보낼 수 없다.

개발자들도 할 말이 많다. 오픈소스 프로젝트와 문서화의 관계에 대한 깃허브 설문조사에 응답한 개발자의 93%가 불완전하거나 명확하지 않은 문서화에 불만이 많았다. 상용 소프트웨어의 상황은 훨씬 낫다. 테크니컬 라이터들이 훨씬 나은 대우를 받기 때문이다. 그런데도 연봉이 충분하지 않다는 문제는 남아 있다.

IT 분야 구직구인 전문 업체 인디드(Indeed)의 연봉 데이터에 따르면 미국 소프트웨어 엔지니어의 평균 기본급은 10만 4,000달러다. 라이트더닥(WriteTheDocs)이 2020년 연봉 관련 설문 조사에서 발표한 미국 테크니컬 라이터 연봉과 크게 다르지 않다. 그러나 평균의 오류에서 벗어나면 상황이 달라진다. 상위에 랭크된 소프트웨어 개발자들의 연봉은 10만 달러를 훨씬 넘기 때문이다. 그러나 상위 25% 테크니컬 라이터의 연봉은 그렇지 않다.

데이터스택스(Datastax)의 CSO 샘 램지와의 대화에 따르면 구글 테크니컬 라이터 패트리샤 보스웰은 훌륭한 코드는 훌륭한 이야기가 필요하다고 강조한다. 대부분의 기술 청중이 이해할 수 있어야 한다는 것이다. 램지는 “주제가 얼마나 기술적인지와 상관 없이, 기본 뼈대는 언제나 좋은 이야기여야 한다”고 주장했다. 램지는 과거 한때 코드는 해독하기 어려웠고 아주 드문 것이었다고 설명한다. 그러나 지금 코드는 그야말로 “넘쳐난다.” 부족한 것은 “누군가가 이미 알고 있는 것과 이미 하고 있는 것을 멈추고 개발자나 기술 청중이 충분히 확인하고 즐길 수 있는, 설득력 있는 이야기”다. 램지는 “그 이야기를 사용해 지역 사회의 일원이 되기 위해 역량을 개발할 수 있어야 한다”고 강조했다.

이때 필요한 것이 바로 좋은 문서다. 좋은 코드의 개발 과정에는 좋은 문서가 필요하다.

코드가 아니라 문서가 주요 인터페이스가 될 경우에 문서는 훨씬 중요하다. 예를 들어 API 기저의 코드를 작업할 경우를 말한다. 그러나 보스웰이 강조한 것처럼 훌륭한 테크니컬 라이터는 단순히 자신이 소프트웨어가 어떻게 작동하기를 바라는지를 기술하는 사람이 아니다. 오히려 훌륭한 테크니컬 라이터는 소프트웨어의 과거 사용 방식을 잘 기술하는 사람이어야 한다. 보스웰은 “그러기 위해서는 시야에 보이는 모든 조각을 한데 묶을 수 있어야 한다. 마케팅 목표, 기능적 목표, 사용자 경험을 하나로 연결하는 완성된 내러티브를 만들어내는 것이다. 테크니컬 라이터는 UX와 협력해 경험을 문서화한다. 여기에서부터 모든 것이 흘러나온다”고 설명했다.

이 능력의 가치가 높다고 생각한다면 아마도 그것이 사실이기 때문일 것이다. 훌륭한 테크니컬 라이터는 왜 이 소프트웨어를 사용해야 하는지 다른 이를 설득하는 것은 물론이고, 미래의 필수 사용자 역시 같은 내러티브 안에서 소프트웨어를 사용하는 방법을 선명하게 그릴 수 있도록 돕는 역할을 한다. 물론 여기에도 전략적 구성 요소가 있지만 테크니컬 라이터의 작업은 매우 전략적인 역할이다.

클라인에 따르면 테크니컬 라이터는 외부에서 가져다 쓰기 어려운 직업이기도 하다. 즉, 훌륭한 테크니컬 라이터를 원하는 조직은 그에 상응하는 비용을 지불할 준비가 되어 있어야 한다. 가장 우수한 개발자보다 더 많은 비용이 들지도 모른다. 개발자만큼이나 우수한 테크니컬 라이터가 없으면 훌륭한 개발자도 빛을 발하지 못할 것이기 때문이다. editor@itworld.co.kr 


X