2011.12.16

기고 | 클라우드 개발 문서의 무모함에 대하여

David Taber | CIO

복잡한 기술에는 개발자들이 효과적으로 사용할 수 있는 개발문서와 교육 자료가 필요하다.  클라우드의 경우, 개발자들이 HTML, 자바스크립트, XML, CSS, 제이쿼리(jquery), 루비(Ruby), PHP, SQL 등 여러 언어를 동시에 다뤄야 하기 때문에 이런 요구가 더 절실할지도 모른다. 그렇다면 클라우드 개발자들에게도 개발문서란 필요한 것인가?

다른 불편 사항들을 알아보자.

• 기술과 친숙한 업체들은 문서 작성에 관심이 없다. 개발자들이 자신들의 코드에 대해 이러쿵저러쿵 지적을 하지 않는데, 그들이 개발문서를 작성하려 할 것 같은가? 또한 해당 업체의 관리자들은 개발문서쯤이야 필요하면 개발 문서를 대신 작성할 사람을 고용하면 된다. 게다가 관리자들은 정보 가공 전문가인 기술 기고가들(tech writers)을 고용할 만큼 강력한 경제적인 동기(economic incentives)를 가지고 있다. 비록 이 기술 기고가들이 개발을 잘 모르더라도 말이다.

• 현재 어느 클라우드 업체 하나가 전체적으로 7,500페이지나 되는 문서를 갖고 있다고 하자. 문서에는 엄청난 투자만큼이나 프로젝트 시작점부터 작성된 글들과 난무하는 데이터 등으로 이미 많은 자료들이 적혀있을 것이다. 실제 시스템에서 기능을 사용할 때는, 개발문서를 볼 필요 없이 구글과 사용자 커뮤니티를 검색하면 된다. 물론 웹의 잘못된 정보 때문에 시간을 낭비하게 될 수도 있다. 하지만 다른 개발자들도 당신처럼 도전과 실패를 반복한다는 것을 알게 된다면 조금은 위안이 될 것이다.

• 모든 고객지원 센터들이 문의 전화의 50%에 대해 답변으로 제시하고 있는 ‘매뉴얼을 읽으세요’ 에 대해 알아 보자. 이러한 대응은 해당 업체의 문서가 잘못됐거나 예시에 관한 내용이 없을 때 무척 ‘효과적’이다. 필자는 최근 한 업체의 개발문서에서 2개의 버그를 찾아 보고했고 수 차례 이메일을 교환했다. 하지만 해결책은 없었고 단지 “저런. 이 업체는 절대로 내가 지적한 문서들을 수정할 생각이 없군”이라는 결론만 얻었다.

• 개발문서는 한 업체가 어떤 기술로 개발됐는지를 다루고 있다. 클라우드의 경우, 업체들의 기술은 물론 웹의 많은 오픈소스 제품들도 함께 사용돼 개발되고 있다. 우리가 작업하는 실제 환경을 문서화할 만큼 시간이 남아 도는 사람도 없을뿐더러, 이는 굳이 일을 크게 벌일 필요는 없다.

• 개발문서는 두꺼운 사전과 같다. 모든 정보가 한 곳에 담겨 있지만, 알고 있는 문법과 단어의 정의만으로는 효과적인 의사소통이 어렵다. 실제로 언어를 배우려면 실제 해당 언어로 된 문서(소설, 신문, 만화책 등)를 읽거나 뉴스, 대화, 노래 등을 들으며 익혀야 한다.

자, 이제 왜 개발문서가 필요 없는지 이유를 알겠는가? 결국, 문서를 읽고 싶어하는 개발자가 없다. 문서를 쓰고 싶어하는 개발자도 없다. 영화 ‘폭력 탈옥(Cool Hand Luke, 1967)’의 명 대사를 빌자면, "우리는 여기서 의사소통에 실패했다"라고 할 수 있다.

이것은 "문서화의 품질"이나 양과는 전현 상관없는 문제다. 즉, "개발자들이 새로운 API를 어떻게 효율적으로 사용할 수 있을까?"라는 문제에 대해 대량의 문서는 그 해답이 될 수 없다는 뜻이다.

유튜브로 해결되지 않는다.
교육 과정? 불가능하다.

이는 어찌 보면 간단하다. 개발자들이 이해하는 언어를 사용하면 되는 것이다. 그것은 다름 아닌 코드(Code)다.




2011.12.16

기고 | 클라우드 개발 문서의 무모함에 대하여

David Taber | CIO

복잡한 기술에는 개발자들이 효과적으로 사용할 수 있는 개발문서와 교육 자료가 필요하다.  클라우드의 경우, 개발자들이 HTML, 자바스크립트, XML, CSS, 제이쿼리(jquery), 루비(Ruby), PHP, SQL 등 여러 언어를 동시에 다뤄야 하기 때문에 이런 요구가 더 절실할지도 모른다. 그렇다면 클라우드 개발자들에게도 개발문서란 필요한 것인가?

다른 불편 사항들을 알아보자.

• 기술과 친숙한 업체들은 문서 작성에 관심이 없다. 개발자들이 자신들의 코드에 대해 이러쿵저러쿵 지적을 하지 않는데, 그들이 개발문서를 작성하려 할 것 같은가? 또한 해당 업체의 관리자들은 개발문서쯤이야 필요하면 개발 문서를 대신 작성할 사람을 고용하면 된다. 게다가 관리자들은 정보 가공 전문가인 기술 기고가들(tech writers)을 고용할 만큼 강력한 경제적인 동기(economic incentives)를 가지고 있다. 비록 이 기술 기고가들이 개발을 잘 모르더라도 말이다.

• 현재 어느 클라우드 업체 하나가 전체적으로 7,500페이지나 되는 문서를 갖고 있다고 하자. 문서에는 엄청난 투자만큼이나 프로젝트 시작점부터 작성된 글들과 난무하는 데이터 등으로 이미 많은 자료들이 적혀있을 것이다. 실제 시스템에서 기능을 사용할 때는, 개발문서를 볼 필요 없이 구글과 사용자 커뮤니티를 검색하면 된다. 물론 웹의 잘못된 정보 때문에 시간을 낭비하게 될 수도 있다. 하지만 다른 개발자들도 당신처럼 도전과 실패를 반복한다는 것을 알게 된다면 조금은 위안이 될 것이다.

• 모든 고객지원 센터들이 문의 전화의 50%에 대해 답변으로 제시하고 있는 ‘매뉴얼을 읽으세요’ 에 대해 알아 보자. 이러한 대응은 해당 업체의 문서가 잘못됐거나 예시에 관한 내용이 없을 때 무척 ‘효과적’이다. 필자는 최근 한 업체의 개발문서에서 2개의 버그를 찾아 보고했고 수 차례 이메일을 교환했다. 하지만 해결책은 없었고 단지 “저런. 이 업체는 절대로 내가 지적한 문서들을 수정할 생각이 없군”이라는 결론만 얻었다.

• 개발문서는 한 업체가 어떤 기술로 개발됐는지를 다루고 있다. 클라우드의 경우, 업체들의 기술은 물론 웹의 많은 오픈소스 제품들도 함께 사용돼 개발되고 있다. 우리가 작업하는 실제 환경을 문서화할 만큼 시간이 남아 도는 사람도 없을뿐더러, 이는 굳이 일을 크게 벌일 필요는 없다.

• 개발문서는 두꺼운 사전과 같다. 모든 정보가 한 곳에 담겨 있지만, 알고 있는 문법과 단어의 정의만으로는 효과적인 의사소통이 어렵다. 실제로 언어를 배우려면 실제 해당 언어로 된 문서(소설, 신문, 만화책 등)를 읽거나 뉴스, 대화, 노래 등을 들으며 익혀야 한다.

자, 이제 왜 개발문서가 필요 없는지 이유를 알겠는가? 결국, 문서를 읽고 싶어하는 개발자가 없다. 문서를 쓰고 싶어하는 개발자도 없다. 영화 ‘폭력 탈옥(Cool Hand Luke, 1967)’의 명 대사를 빌자면, "우리는 여기서 의사소통에 실패했다"라고 할 수 있다.

이것은 "문서화의 품질"이나 양과는 전현 상관없는 문제다. 즉, "개발자들이 새로운 API를 어떻게 효율적으로 사용할 수 있을까?"라는 문제에 대해 대량의 문서는 그 해답이 될 수 없다는 뜻이다.

유튜브로 해결되지 않는다.
교육 과정? 불가능하다.

이는 어찌 보면 간단하다. 개발자들이 이해하는 언어를 사용하면 되는 것이다. 그것은 다름 아닌 코드(Code)다.


X