LINE Engineering
Blog

API the Docs 참관 후기

Serizawa 2018.05.30

LINE 플랫폼 개발자용 문서를 담당하고 있는 테크니컬 라이터입니다.

안녕하세요? 테크니컬 라이터 Serizawa입니다. LINE은 개발자들이 최신 기술 동향을 파악할 수 있도록 해외 컨퍼런스 참가를 지원합니다. 이번 포스팅에서는 제가 이 지원 제도를 이용해 다녀온 API 문서화 관련 컨퍼런스인 API the Docs에 대해 전해 드릴까 합니다.

API the Docs는 테크니컬 라이터, API 개발자, 프로덕트 오너, 에반젤리스트를 대상으로 한 API 문서화에 특화된 행사로, 해마다 여러 차례, 세계 각지에서 열립니다. 개발 경험(Developer eXperience, 이하 'DX')의 중요 요소인 문서화에 관해서 최신 우수 사례나 경향 등을 공유하고 의견을 나누는 자리이지요.

이번 행사는 2018년 4월 24일, 파리 시내 중심부에 있는 Mozilla 사무실에서 열렸습니다. API 전문가, 콘텐츠 전략가, 소프트웨어 개발자 등 다양한 위치에서 API 문서 및 개발자 포털의 개발, 운영에 종사하는 분들께서 총 열 가지 테마로 강연을 진행해 주셨습니다. 강연 내용은 ‘개발자 사이트가 갖춰야 할 요소’와 같은 전반적인 논의부터, OpenAPI를 이용해 문서를 생성하는 기술과 방법, 혹은 사이트의 기반이 되는 플랫폼을 변경할 때의 고생담 같은 구체적인 정보에 이르기까지 다양했습니다. 이번 글에서는 LINE 플랫폼의 API 문서 작업을 담당하는 테크니컬 라이터의 입장에서 특히 흥미로웠던 강연을 소개할까 합니다.

각 강연의 개요 및 관련 자료는 Pronovix의 블로그 포스팅, API the Docs Paris 2018을 참고하시기 바랍니다. OpenAPI 관련 업무 종사자라면 관심이 갈 만한 주제를 발견하실 수 있을 것입니다.

PSD2 시행 이후 뱅킹 API 포털의 현재

이 강연은 API Academy의 Lead API Economist인 Mehdi Medjaoui씨께서 진행해 주셨습니다.

PSD2(Second Payment Services Directive)란 EU의 결제 서비스 지침 개정안으로, 2016년 1월부터 시행되었습니다. 이 지침에 따르면 금융 기관은 고객이 동의한 경우 해당 고객의 계좌 정보를 서드 파티에 제공하도록 되어 있습니다. 이로 인해 핀테크 서비스가 활성화되고 고객 편의가 향상되리라 기대됩니다. PSD2를 준수하는 금융 기관에서는 개발자 사이트를 구축하여 고객의 계좌 정보를 취득하고, 이체 요청을 실행할 수 있는 API를 공개하고 있는데, Medjaoui씨는 이 가운데 은행 여덟 곳의 개발자 사이트를 비교하며 선도적 사이트에는 어떤 기능이 갖춰져 있는지 자세히 설명하였습니다.

은행별로 개발자 사이트의 편리성에는 차이가 있었지만, 원활한 사용자 등록 절차나 API 작동을 실제 테스트해 볼 수 있는 샌드박스 등 서드 파티 개발자가 개발자 사이트에 요구하는 요소를 두루 갖춘 곳은 비교 대상 사이트 중에는 없었습니다. 그렇다 보니 핀테크 업계의 선두주자인 StripeSquare의 수준을 따라잡으려면 개선이 필요하겠다는 내용이었지요. 글로벌 은행과 같은 대기업에서도 시행착오가 이어지고 있으며, API 공개나 이용 활성화 방안은 아직 확립되지 않은 상태임을 알 수 있었습니다.

Medjaoui씨의 발표 슬라이드에는 개발자가 원하는 개발자 사이트 요소와 이용하기 편한 사이트의 사례들이 열거되어 있습니다. 그날 그날의 업무에 쫓겨 미처 생각하지 못했지만 구현하면 분명 편리할 것 같은 기능들을 발견할 수 있어 무척 유익한 시간이었습니다.

DX 설계: 개발자 사이트가 제공해야 할 문서란?

이 강연은 Pronovix의 테크니컬 라이터이신 Kathleen De Roo씨가 맡아주셨습니다.

DX를 설계한다는 것은 어떤 것일까요? 개발자 포털에서는, 개발자가 개발 주기 상의 각 단계에서 직면하는 문제에 직접 대처할 수 있도록 다양한 문서를 제공하는 방법을 설계하는 것을 말합니다. 강연에서는 각 단계별로 개발자에게 어떤 문서 카테고리가 필요한지, 목적과 대상 독자가 다른 각종 문서에 쉽게 접근하려면 메인 화면의 디자인은 어떻게 해야 하는지, 또 개발자 포털의 신뢰도를 높이기 위해서는 어떤 항목을 갖추어야 하는지에 대해서 구체적인 모범 사례 소개가 이어졌습니다.

외부 개발자가 공개된 API로 제품을 개발해서 운용하는 단계에 이르기까지, 개발자 사이트는 셀프 서비스 형태의 지원을 제공하는 허브 역할을 하게 됩니다(포털이 잘 만들어져 있으면 지원 요청 건수는 줄어듭니다. 예를 들어 앞에서 언급한 Stripe의 경우, 문의 고객은 전체의 10% 미만이라고 합니다). 뛰어난 DX를 제공하기 위해서는 시범 단계에서 실제 운용에 이르기까지 각 단계별로 개발자를 적절히 지원할 수 있도록 다양한 카테고리의 문서가 구비되어 있어야 합니다. 가령 API를 한번 테스트해 보고 싶은 개발자에게는 API의 개요를 간단히 파악하고 작동 상황을 확인할 수 있는 페이지를, 유료 API라면, API를 실제 이용해 보고자 하는 개발자에게는 요금제나 서비스와 시스템 정보를 제공할 수 있어야 합니다. 또, 구현 단계에 있는 개발자에게는 자주 발생하는 문제를 정리해 놓은 FAQ 페이지나 다른 개발자들과 의견을 교환할 수 있는 포럼이 갖춰져 있다면 도움이 되겠지요.

특히 인상 깊었던 것은, 개발자 사이트에서 무엇을 달성하고자 하는지 생각할 때 ‘외부 개발자를 API의 팬으로 만든다’는 목표가 있어야 한다는 생각이었습니다. 개발자 사이트를 운영하는 데 있어서, API 자료 자체를 완전히 준비해 놓는 것뿐 아니라 커뮤니티 활성화, 블로그를 통한 정보 제공을 담당하는 Developer Relations팀과의 연계를 빠뜨릴 수 없겠지요.

OpenAPI 활용 방안, 문서 작업 그 이상

이 강연은 Stoplight의 Lead Community Engineer인 Taylor Barnett씨의 진행으로 이루어졌습니다.

OpenAPI(구 Swagger) 사양은 REST API를 작성하기 위한 열린 규격입니다. 강연에서는 API 설계 지원 및 목업(mockup) 작성, API가 사양대로 구현되어 있는지 확인하기 등, OpenAPI 사양의 다양한 활용 방안이 소개되었습니다.

OpenAPI에서는 구조화된 접근 방식을 취하고 있기 때문에 이를 문서화 도구로 이용하면 아무 것도 없는 상태에서 써내려갈 때보다 쉽고 빨리, 그리고 통일된 용어를 사용해서 문서를 작성할 수 있습니다. 그런데 이뿐 아니라 API 개발자의 DX 향상에도 OpenAPI를 활용할 수 있다는 사실을 알고 있는 사람은 아직 그다지 많지 않은 모양입니다. Barnett씨는 이 점에 주목하여 엔지니어의 관점에서 API 설계, 목업, 테스트, 피드백의 네 가지 영역에서 OpenAPI를 업무에 활용했을 때의 장점을 설명해 주었습니다.

모든 영역에 공통되는 장점은 ‘구현될 때까지 기다리지 않고 테스트할 수 있다’, ‘자동화로 누락을 방지할 수 있다’, ‘공통 포맷으로 협동을 도모한다’는 점입니다. 실제로 구현된 것과 문서 사이의 차이를 체크하는 프레임워크인 Dredd 린터인 speccy 등도 공개되어 있습니다. 이 강연의 제목은 ‘Going to Infinity and Beyond Documentation with OpenAPI(OpenAPI 활용, 문서 작업을 너머 무한으로)’였는데, 말 그대로 OpenAPI를 기반으로 하는 API 개발에 펼쳐진 커다란 가능성을 느낄 수 있었습니다.

글을 맺으며

저에게는 이번이 첫 해외 컨퍼런스 참가였는데요, API 문서화 분야에서 요구되는 다양한 전문성에 압도당하는 느낌이었습니다. 독자가 이해할 수 있는 콘텐츠를 작성하는 것은 테크니컬 커뮤니케이션 업무의 극히 일부에 불과합니다. 이용하기 편하고 신뢰할 수 있는 개발자 사이트를 유지하며 그 기술적 토대를 효율적이고 지속적으로 개선해 나가기 위해서는, 다양한 기술 분야에서 저마다 강점을 지닌 멤버들이 한 팀이 되어 일할 필요가 있겠다는 생각이 들었습니다.

동시에 지금의 LINE Developers 사이트를 더욱 개선시킬 수 있는 구체적인 힌트도 곳곳에서 발견할 수 있었습니다. 가능한 것부터 하나씩 사이트 개선에 활용할 생각입니다.

마지막으로 LINE의 영어 및 일본어 테크니컬 라이터 채용 공고를 전하면서 글을 맺을까 합니다. 저희와 함께 기술 문서 작업의 가능성을 추구해보고 싶으신 분께서는 아래 양식을 통해 지원해 주시기 바랍니다. 여러분의 적극적인 참여를 기다리고 있겠습니다.

Technical writing

Serizawa 2018.05.30

LINE 플랫폼 개발자용 문서를 담당하고 있는 테크니컬 라이터입니다.

Add this entry to Hatena bookmark

리스트로 돌아가기