! This post is also available in the following languages. 영어, 일어

LINE 개발자 사이트 개편 – 비하인드 스토리

안녕하세요, 저는 LINE의 서비스 제품에 대한 기술 문서를 담당하는 테크니컬 라이터, 케네스 라우(Kenneth Lau)입니다. 아마 이미 아시는 분들도 계시겠지만, 저희는 최근에 LINE 개발자 사이트를 개편하였습니다. LINE 개발자 사이트는 LINE Login이나 메시지 API 등 LINE이 제공하는 서비스에 대한 정보와, 여러분의 앱을 관리할 수 있는 개발자 콘솔을 제공합니다. 무엇을 개편하였는지 간략하게 소개하는 글을 준비하였으니 궁금하신 분들은 확인해 보세요.

저는 이번 글을 통해서 개발자 사이트 개편에 따른 기술적 변화와, 기술 문서를 작성하는 과정에 대해 다루고자 합니다. Static site generator를 도입한 과정과 이로 인해 문서화에 생긴 변화와 앞으로 저희가 어떤 계획을 가지고 있는지에 대해 말씀드리겠습니다. 그 전에, 우선 개발자 사이트에 대해서 간략하게 소개 드리겠습니다.

LINE 개발자 사이트에 대하여

LINE 개발자 사이트(영문 명칭: LINE Developers site)는 LINE Login이나 메시지 API 등 LINE이 제공하는 서비스를 활용하고자 하는 고객을 위한 포털 사이트입니다. 개발자 사이트는 서비스 제품에 대한 문서, LINE 플랫폼에 대한 최신 소식과 함께 여러분들이 궁금해하실만한 내용을 다루는 FAQ를 함께 제공하고 있습니다. 물론 SDK와 같이 다양한 자원도 다운로드하실 수 있도록 제공하고 있습니다.

개발자 사이트는 문서와 자원뿐만 아니라, 여러분의 앱을 LINE 플랫폼과 연동하기 위해 사용하는 채널을 관리할 수 있는 개발자 콘솔도 함께 제공하고 있습니다. 사이트 개편을 통해 여러분의 서비스를 개편 전보다 쉽고 빠르게 LINE 서비스와 연동하실 수 있도록 채널 생성 과정과 설정 과정을 간소화하였습니다. LINE Login 서비스를 여러분의 서비스와 연동하거나, LINE 챗봇을 만들어 보시려면, LINE 개발자 사이트를 방문해 보세요.

New LINE Developers Site

WordPress에서 static site generator로

이번 개편에서는 지금까지 사용하던 WordPress를 떠나보내고 static site generator를 도입하기로 결정하였습니다. 동적으로 사이트를 빌드하는 WordPress와 달리 static site generator는 문서 작성자가 작성한 소스(문서)를 기반으로 정적인 HTML 파일들을 생성합니다. 도구를 변경한 이유는 static site generator를 도입하면 우리의 문서를 보다 더 소스 코드처럼 대할 수 있으며 깃허브의 워크플로를 문서화에 적용할 수 있기 때문이었습니다. WordPress를 이용했을 때는 특정 관련인들만 콘텐츠에 접근할 수 있었지만 우리의 콘텐츠는 이제 깃허브 저장소에 저장되기 때문에 LINE 개발자들이 콘텐츠에 자유롭게 접근할 수 있게 되었습니다.

Static site generator의 또 다른 장점은 사이트의 로딩 속도가 빨라진다는 것입니다. 이는 이미 빌드된 정적인 HTML 페이지를 로딩하기 때문이며, 더 이상 우리의 콘텐츠를 동적으로 생성해내거나 데이터베이스에 쿼리할 필요가 없어졌습니다. WordPress를 이용했을 때 사이트의 보안을 위해 정기적으로 보안 패치를 적용했던 행정적 관리 요소들 또한 사라지게 되었습니다.

우리는 많은 static site generator들 가운데 Middleman을 선택하였습니다. Middleman은 자유롭게 커스터마이제이션 할 수 있었기 때문에 우리의 다양한 요구 사항들을 모두 만족시킬 수 있다고 판단하였기 때문입니다. 자, 이제 우리의 개발자 사이트에 static site generator를 어떻게 적용하였는지 소개해 드리겠습니다.

Middleman 적용하기

Middleman은 오픈소스 기반의 static site generator로, Ruby로 구현되어 있으며 활발한 개발자 커뮤니티를 가지고 있습니다. Middleman 덕분에 우리는 문서를 마크다운(Markdown)으로 작성하고, 콘텐츠를 재사용하고, 여러 개의 레이아웃을 구성하고, 하나의 콘텐츠를 여러 언어로 제공할 수 있게 되었습니다. 저희 사이트에 Middleman을 어떻게 적용했는지 조금 더 상세하게 소개 드리겠습니다.

Redcarpet으로 마크다운 렌더링하기

우리는 마크다운으로 문서를 작성한 후 Redcarpet을 이용하여 문서를 파싱하여 HTML 파일로 생성하였습니다. 마크다운은 가벼우면서도 가독성이 높지만, 예를 들어, 표준 형태가 아닌 표를 사용할 때 등의 예외 상황에서 Redcarpet은 우리의 요구 사항을 모두 만족시키지 못했습니다. 이런 예외 상황이 발생하면, Redcarpet의 특별한 기능인 커스텀 마크다운 요소를 활용하여, 우리만의 마크다운을 정의하여 사용하였습니다. 예를 들어, 다음의 그림에서와 같이 표의 제목이 표의 위쪽에 위치하는 대신 왼쪽 행에 위치하도록 하기 위해 커스텀 요소를 만들었습니다.

Custom element applied on LINE Developers site

다음은 위 표와 같이 보이게 하기 위해 만든 커스텀 마크다운 요소입니다

|>|
|| **Superclass** | `NSObject` |
|| **Declared in** | LineSDKAPI.h |
|>|

ERB 템플릿

우리는 문서, 뉴스, FAQ 항목, API 레퍼런스 가이드 별로 별도의 템플릿을 만들기 위해 ERB (Embededded RuBy) 템플릿 언어를 활용했습니다. Middleman을 이용하면 ERB 템플릿에 변수와 다양한 helper methods를 적용하여 내용이 동적으로 구성되게 하고 구성된 내용을 정적 HTML 파일로 추출할 수 있습니다. 우리는 템플릿이 특정 마크다운 파일이나 HTML 파일에 적용될 수 있도록 템플릿 파일들을 layouts 폴더에 저장하였습니다.

YAML 데이터 파일

최상단 페이지와 우리 사이트의 내비게이션 바를 관리하기 위해 YAML 데이터 파일을 이용했습니다. YAML 데이터 파일을 활용하는 것이 효과적인 이유는, HTML 파일을 직접 수정하지 않아도 되며, 읽기 쉬운 포맷으로 구성된 데이터를 쉽고 간단하게 바꿀 수 있기 때문입니다. 예를 들어, 다음 그림에 나타난 내비게이션 바를 제공하기 위해 그림 아래의 YAML 데이터 파일을 정의하였습니다.

sidebar_title_en: "iOS SDK"
menu_items:
  - title_en: "Guides"
    url:
    subpages:
    - title_en: "Overview"
      url: "/docs/ios-sdk/overview"
      subpages: []
    - title_en: "Logging out users"
      url: "/docs/ios-sdk/logging-out-users"
      subpages: []
    - title_en: "Getting user profiles"
      url: "/docs/ios-sdk/getting-user-profiles"
      subpages: []
    - title_en: "Managing access tokens"
      url: "/docs/ios-sdk/managing-access-tokens"
      subpages: []

콘텐츠 재사용하기

반복되는 콘텐츠가 등장하는 곳마다 매번 작성하는 번거로움을 없애고 콘텐츠를 재사용하고자, 재사용 대상 콘텐츠를 별도의 마크다운 파일에 담고 이 파일들을 partials라는 폴더에 넣었습니다. 재사용되는 콘텐츠가 나타나야 하는 곳에서는 Middleman의 partial 메서드나 문서의 YAML Frontmatter에 파일 이름을 명시하는 방법을 활용합니다. LINE 개발자 사이트에서는 API 레퍼런스 문서와 에러 설명 부분에서 partial 파일을 활용하여 콘텐츠를 재사용하였습니다. 다음의 스크린샷은 콘텐츠가 재사용된 사례를 보여줍니다. 스크린샷의 콘텐츠에 대한 마크다운은 그림 아래에 있습니다. 보시면 에러 설명 섹션(Status codes)에 대한 마크다운 대신 partial 메서드가 활용된 것을 보실 수 있습니다.

### Error response

If the refresh token is invalid, a `400 Bad Request` status code is returned with the following JSON object.

```json
{
    "error": "invalid_grant",
    "error_description": "invalid refresh_token"
}
```

<%= partial "partials/documentation-partials/line-login/error-responses" %>

로컬리제이션

이번 개발자 사이트 개편의 주요 목표 중 하나는 다국어 지원이었습니다. 개편 전에는 영어로만 정보를 제공했으나, 이번 개편을 통해 일본어를 추가하였습니다. 다국어 지원을 위해 Middleman의 internationalization (i18n) 기능을 활용하였습니다. enja라는 이름을 가진 각각의 YAML 파일에 특정 키에 대한 영어 값과 일본어 값을 정의하고, i18n helper method를 이용하여 우리의 문서 템플릿에서 이 키에 대한 값을 조회하여 삽입되도록 하였습니다. 예를 들어 documentation이라는 키의 영어 값은 “English”이고, 일본어 값은 “ドキュメント”입니다.

Middleman은 문서의 언어에 따른 언어별 경로(URL)을 생성해 줍니다. 개발자 사이트의 기본 언어는 영어로 설정하고, 일본어 문서에는 파일 이름에 ja를 포함시켰습니다. 사이트를 빌드할 때 Middleman은 파일명의 언어 코드를 참고하여 자동으로 해당 문서로의 경로를 언어 코드가 들어간 URL로 생성합니다.

깃허브를 문서 저장소로

WordPress가 아닌 Middleman을 사용하게 됨에 따라 우리는 문서를 깃허브에 저장하고 관리할 수 있게 되었습니다. LINE 개발자들 모두 깃에 접속할 수 있고, 매일 깃허브 엔터프라이즈를 사용하기 때문에, 어느 개발자든지 개발자 사이트 문서 저장소에 풀 리퀘스트를 올릴 수 있게 되었습니다. 문서화 과정에 깃허브의 워크플로를 적용하면 테크니컬 라이터와 개발팀과의 거리가 좁혀지고, 개발자와의 협업이 수월해지는 장점이 있습니다. 깃허브에 문서가 저장되면 문서는 어떻게 검토할 수 있을까요? 개발자들이 코드를 리뷰하는 방법과 동일하게 풀 리퀘스트를 통해 문서를 검토할 수 있습니다.

사이트 빌드는 Jenkins로

LINE 개발자 사이트를 테스트하고 빌드하는 과정을 자동화하기 위해 Jenkins를 도입하였습니다. 누군가 문서를 작성 혹은 변경하여 풀 리퀘스트를 생성하면, Jenkins는 해당 변경 사항이 적용되어도 사이트가 빌드될 수 있는지 자동으로 확인합니다. Jenkins의 검증이 이뤄지면 문서 검토자는 풀 리퀘스트로 올라온 문서의 내용을 확인하고, 문서에 문제가 없으면 마스터 브랜치에 변경 사항을 적용(머지)합니다. 마스터 브랜치에 머지가 발생하면 Jenkins는 또다시 자동으로 스크립트를 실행하여 문서를 빌드하고 추출된 Middleman 사이트를 베타 서버에 배포합니다. 빌드된 사이트는 베타 서버에서 다시 한번 검토 과정을 거친 후, 프로덕션 서버로 배포됩니다.

문서화를 코딩처럼

Static site generator를 이용하면 개발자들에게 익숙한 깃허브 워크플로를 문서화에 적용할 수 있습니다. 이번 개편에 깃허브 워크플로를 문서화에 적용한 결과, 라이터들 입장에서는 개발팀과의 협업이 수월해졌습니다. 문서에 대한 접근성이 높아진 만큼, 앞으로도 사내 개발자들이 외부용 기술 문서에 더욱 큰 관심을 가지고 협업하고 기여할 수 있기를 기대합니다. 궁극적으로 이러한 방법이 사이트 콘텐츠 업데이트 속도를 높이고, 우리의 문서를 활용하는 고객에게 보다 더 높은 수준의 문서를 제공할 수 있게 되리라 생각합니다.

향후 계획

이번 개편은 LINE 개발자 사이트 담당 팀에게 있어서는 문서 개선의 시작 단계입니다. 다음 단계로는, 문서의 품질을 향상시키고 신규 콘텐츠를 신속하게 게시하기 위한 절차를 자동화할 계획이 있습니다. 예를 들어 링크 유효성 검증하기, 스타일 변경하기와 API 레퍼런스 자동 추출 등이 대상입니다. 추가적으로 검색 기능을 개선하고 내비게이션 기능을 강화하여, 여러분이 원하는 정보를 쉽고 빠르게 찾으실 수 있도록 개선해 나가려고 합니다.

내용적인 측면에서는, LINE의 서비스를 활용하여 여러분이 더 멋진 앱을 개발하실 수 있도록, 더 많은 내용을 제공하고 문서 내용을 더 자주 업데이트하려고 합니다. 또한, 여러분에게 나은 개발 경험을 드리고자 여러분의 소중한 의견을 받을 수 있는 창구를 더 마련할 계획도 있습니다. 많은 개선 사항들이 앞으로도 적용될 예정이니 기대해 주시기 바랍니다.

LINE 개발자 사이트에서 제공하는 최신 소식을 빨리 받고 싶으신 분은 아래의 QR 코드를 이용하여 LINE Developers official account를 친구로 추가해 주세요.

글을 맺으며

LINE 개발자 사이트 개편에 관계된 기술에 대해 더 많은 정보를 알고 싶으시다면, 최근 개최되었던 LINE Developers Day에서 발표한 마크 세라노 개발자 사이트 기술 리더의 발표를 확인해 보세요.