Confluence를 활용한 ShopLocal의 API 기술 문서 작성 사례를 확인해 보세요
- 콘텐츠 마케팅 담당 이사 Jon Silvers 작성
- 뉴스
 설립: 1999년 사무실: 일리노이주 시카고에 본사 산업: 다중 채널 마케팅 서비스 직원 수: 약 225명 사용 도구: Confluence, JIRA |
다중 채널 마케팅 서비스의 선두주자인 ShopLocal은 광고주와 소비자를 온라인/오프라인(점포)으로 연결해주는 혁신적이고 완전한 디지털 솔루션 패키지를 제공합니다.
ShopLocal 의 업계를 선도하는 SmartProduct 비즈니스 솔루션(SmartCircular, SmartCatalog, SmartDelivery)은 Target, Best Buy, Home Depot, CVS, Albertsons, Sears를 비롯한 전국 상위권 소매업체 중 100개 이상의 업체에서 온라인 안내문, 디스플레이 광고, 검색, 소셜 미디어, 옥외 디지털 및 모바일 경로를 통해 쇼핑객에게 고도로 상호적이고 대상이 지정되고 지역화된 프로모션을 수행할 수 있게 합니다. ShopLocal은 Gannett Co., Inc.가 전체 지분을 소유한 PointRoll의 소매 부문을 담당합니다.
인터뷰
Confluence에 대해서 어떻게 들으셨습니까?
이전 회사에서 Confluence를 사용한 적이 있습니다. 꽤 초기였던 Confluence 1.10 버전 때부터 사용하기 시작했습니다. Confluence는 정확히 원하는 것을 제공합니다.
우리는 아주 빠른 속도로 기존 콘텐츠를 모두 변환하고, 하나의 조직으로서의 공동 작업 방식을 실질적으로 변화시킬 수 있었습니다.
wiki는 조직의 생명선으로 API 문서에서 정책과 프로세스와 같은 수많은 내부 계획까지 모든 것에 wiki를 사용합니다.
wiki 는 우리 조직의 지식 기반입니다. PointRoll에서 ShopLocal을 인수했을 때 우리는 Universal Wiki Converter를 사용하여 PointRoll의 SocialText wiki를 Confluence로 쉽게 마이그레이션할 수 있었습니다. 2010년 9월 기준으로 우리 wiki는 12,000페이지 이상 그리고 58,000페이지 버전 이상을 보유하고 있습니다.
API 문서와 관련해서 누가 문서를 작성하고 누가 봅니까?
문서 작성은 제품 관리와 개발자의 공동 작업입니다. 이론상으로는 조직의 누구나 새 문서를 편집하거나 작성할 수 있지만 실제로는 편집하는 게 핵심 개발자밖에 없었습니다.
우리는 권한을 제한하여 고객은 페이지를 편집할 수 없지만 메모를 남길 수는 있게 만들었습니다.
우리는 애자일 개발 작업장이라 사용자 스토리를 취합하여 높은 수준의 릴리스 정보로 변환하는 일이 원활합니다. 우리는 여러 응용프로그램에서 일관성을 유지하고 싶었습니다.
모 든 API 호출에는 XML 및 JSON 형식으로 된 예상 출력 외에도 짤막한 설명과 필수, 옵션, 조건부 매개 변수와 URL 예가 포함됩니다. 다양한 기업에서 본사 API를 사용하여 소매업체(Target, the Best Buy, Staples, 전 세계의 Home Depot)와 이들의 개발 에이전시를 포함한 다양한 매개체를 통해 로컬 거래를 독립 응용프로그램 개발자에게 배포하고 있습니다.
우리는 다양한 개발자, 에이전시, 소매업체와 작업합니다. 문서의 주된 목적은 사람들이 API를 채택하고 즉시 응용프로그램을 구축하는 일을 쉽게 만들기 위해서입니다.
wiki 전에는 문서화 작업에 무엇을 사용하셨습니까?
Confluence를 사용하기 전에는 API 문서를 배포하기 위해 100페이지 짜리 Microsoft Word를 사용했습니다. 회사 문서에 Word를 사용하면 의도하지 않은 문제가 많이 발생했습니다.
예 를 들어 우리는 우리의 API를 버전화해서 거의 매 분기에 새 릴리스를 내놓습니다. 아시다시피 Word 문서를 서로 주고받다 보니 가끔 개발자가 최신 정보를 얻지 못해 이전 릴리스로 개발하거나 잘못된 명명법을 사용하는 일이 있었습니다.
또 변경 사항을 알리기도 아주 어려웠습니다. 업데이트를 배포하는 것은 이메일을 수단으로 삼았습니다.
어떤 경우에는 개발자가 문서를 마지막으로 요청한 때가 1년 전이었던 경우도 있었습니다. 여러 버전의 문서를 넘나드는 Word에 비해 wiki를 사용해서 가장 좋았던 건 제대로 된 원본이 항상 하나라는 점입니다.
Confluence로의 콘텐츠 마이그레이션에 대해 말씀해 주세요.
Confluence 로 바꾸고 나서 Word 문서를 다시 만드는 것보다 더 많은 일을 해보고 싶었습니다. wiki만이 제공할 수 있는 고유한 기능을 활용해보고 싶었습니다. 우리가 정한 첫 번째 목표는 어떻게 하면 사람들이 쉽게 사용하게 만들까였습니다. wiki를 사용하여 페이지를 서로 연결하고 코드 스니핏(snippits)을 삽입하고 SLA 정보를 지원하고 사용 약관을 게시할 수 있었습니다.
우리의 목표는 개발자가 API를 쉽게 사용하게 만드는 것이었습니다. 개발자에게 코드 사용 방법에 대한 정보와 예를 제공하고 싶었습니다. wiki는 우리가 정보를 강화할 기회를 주었습니다.
문서에 플러그인도 사용하십니까?
아니요, 사용 안 합니다. Confluence는 우리에게 알맞는 바로 사용 가능한 무료 플러그인과 매크로를 함께 제공하며, 우리는 현재 문서화 테마를 사용하고 있습니다.
일관성을 위해서 Confluence의 페이지 템플릿을 사용하고 있습니다. API 호출은 모두 일관된 모양으로 되어 있고 정보의 종류도 페이지에 상관없이 일관성이 있습니다.
그리고 레이블별 콘텐츠 매크로를 꽤 많이 사용합니다. 예를 들어, FAQ에 사용합니다. 이 매크로에 API FAQ에 태그를 붙인 다음 매크로를 사용하여 페이지가 동적으로 작성되게 합니다.
또 한, 코드 매크로도 꽤 많이 사용합니다. 아마도 제가 가장 많이 사용하는 것 중의 하나는 포함 라이브러리(include 관련 매크로)일 것입니다. 저는 사실 포함 라이브러리의 광팬입니다. 루트 수준에 정보를 넣고 페이지 포함으로 다른 페이지에 콘텐츠를 삽입할 수 있습니다. 그 한 가지 예가 버전 관리입니다. 우리가 가진 API 버전이 여러 개이기 때문에 "이전 버전 참조"라는 부분을 최신 버전 링크와 함께 포함시킵니다. 한 곳에서 변경하면 사항이 해당 포함 페이지를 가진 페이지가 모두 업데이트되기 때문에 포함 라이브러리는 절감해주는 시간은 막대합니다.
문서에 wiki를 사용하는 데 따르는 혜택은 무엇입니까?
우 리가 추가적으로 경험한 혜택으로는 문서 일관성도 있습니다. 이제 개발자는 항상 최신 버전의 문서를 가질 수 있고 최신 버전을 어디서 받을지도 알고 있습니다. 개발자는 페이지를 지켜보기 때문에 변경 사항이 생기면 알림을 받게 됩니다. 메모를 사용해서 질문을 하거나 문서에 대한 피드백을 제공할 수 있습니다. 이렇게 되면 제품 관리자는 피드백을 얻기가 수월해 집니다. 현재 구축 대상의 상태를 확인하는 데 도움이 되기 때문입니다.
지금까지 본 것 중 최고의 API 문서는 사람들이 응용프로그램을 구축하는 일을 간편하게 만들어 주었습니다. 그렇게 만드는 것이 우리의 목표였습니다. 우리는 예전에 비해 많은 진전을 이루었습니다. 분명히 Confluence가 여기에 큰 몫을 했습니다.
생각지도 못했던 혜택 중 한 가지는 고객과 문서를 통해 대화하는 시간이 줄었다는 것입니다. 이제는 문서에 대해 설명할 필요 없이 고객이 구축하기 원하는 응용프로그램에 대해 바로 이야기를 할 수 있게 되었습니다.
감사합니다, Brendan!
댓글