LINE Engineering
Blog

How we redesigned the LINE Developers documentation site

Kenneth Lau 2017.11.07

Technical writer in charge of developer documentation for the LINE Platform

Hi, my name is Kenneth Lau and I'm a technical writer working on the documentation for our developer products here at LINE. As you may have already noticed, we recently released a major update to our LINE Developers site, which provides information about our developer products such as LINE Login and the Messaging API and a developer console for managing your apps. For a quick breakdown of the changes to the site, see our Introducing the redesigned LINE Developers site news post.

In this blog post, I'd like to focus on the changes we've made to the technology that runs behind the site and our authoring process for developer documentation. I'll talk about how we switched to using a static site generator, how this has affected the way we develop docs, and what changes we plan to make in the future. But first, let me give you a brief introduction to the LINE Developers site.

About the LINE Developers site

The LINE Developers site is a portal site for developers who want to use our developer products such as LINE Login and the Messaging API. On the site, you can find our product documentation, the latest news about the LINE Platform, and an FAQ section to provide answers to your questions. It also provides access to SDKs and other resources that we've made available to developers.

Another component of the LINE Developers site is the developer console which lets you manage the channels used to integrate your apps with the LINE Platform. As part of the site redesign, we have streamlined the process of creating and setting up channels so that you can get up and running with our developer products in fewer steps than before. If you'd like to try implementing LINE Login or creating a LINE chatbot, check out the LINE Developers site.

New LINE Developers Site

From WordPress to a static site generator

In this major update of our documentation site, we decided to switch from using WordPress to a static site generator. Unlike WordPress which builds the site dynamically, a static site generator simply takes our sources files and generates static HTML pages. We favored this approach because it allows us to treat our documentation more like source code and adopt a Git workflow for docs. Our content can now be stored in a GitHub repository which can be easily accessed and viewed by our engineers unlike with WordPress, which was only used and accessible to certain content creators.

Another advantage of using a static site generator is that it allows for a faster site since we are just loading pre-built static HTML pages. This removes the need to dynamically generate our content or to make any database queries. Also, using a static site generator reduces the administrative overhead of maintaining our WordPress instance which includes regularly installing security patches to ensure the security of the site.

While there are many static site generators available today, we decided to use Middleman as we felt it was highly customizable and would be able to serve our needs. Next we'll talk about how we implemented it in our site.

Using Middleman

Middleman is an open-sourced static site generator that is built with Ruby and has an active developer community. With Middleman, we were able to author our documentation in Markdown, create reusable content, develop multiple layouts, and display content in multiple languages. Here, I'll go over some of the details of how we implemented Middleman in our site.

Markdown rendering with Redcarpet

Our documentation is authored in Markdown which is then parsed and rendered into HTML using Redcarpet. Although Markdown is a lightweight and readable markup language, we found that in certain situations, such as creating non-standard tables, Redcarpet was not able to satisfy our requirements. In such cases, we used Redcarpet's ability to create our own custom Markdown elements as a workaround. For example, we created a custom element for creating tables with a table header on the left column instead of the top row.

Custom element applied on LINE Developers site

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

ERB templates

We used the ERB (Embedded RuBy) templating language to create separate templates for our articles, news posts, FAQ items, and API reference pages. With Middleman, we can include variables and various helper methods in our dynamic ERB templates which are then output as static HTML pages. We then stored our templates in a layouts folder where they can be applied to specific Markdown or HTML files as necessary.

YAML data files

We used YAML data files to manage certain content on the top pages and navigation bars on our site. Using data files is effective because it makes it easier for writers to simply edit values in an easy-to-read format, instead of having to work directly in an HTML file. For example, the following sidebar content is extracted using the values from the YAML data file.

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: []

Reusable content

To reuse content across our site, we created Markdown files in a partials folder in our repository. The content in these files can then be used in multiple pages by using the partial method or by specifying the filename in the YAML Frontmatter of our documents. In our implementation, we put our API reference documentation and other reusable content such as error descriptions in partial files to allow for reuse across multiple pages. The following example shows how we included a table of error responses into a document using the partial method.

### Error response

If the refresh token is invalid, a <code>400 Bad Request</code> 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"%>

Localization

One of our goals for the redesign was to add multi-language support to the site. Originally, our documentation was only available in English but we have added Japanese to the site. To create a multi-language site, we used Middleman's internationalization (i18n) features. We mapped English and Japanese values to specific keys in en and ja YAML files and used the i18n helper method to refer to the keys in our templates. For example, our documentation key corresponds to a value of "Documentation" in English and "ドキュメント" in Japanese.

With Middleman we can also create localized paths for our English and Japanese pages. We set English as our default language and by including ja in our document filenames, localized paths are created by Middleman.

Creating a doc repository on GitHub

Now that we are using Middleman instead of WordPress, we can store and manage our source files in a GitHub repository. Since all of our engineers have access to and generally use GitHub Enterprise in their daily work, this makes it much easier for anyone to file an issue in our repository or to make a pull request. For writers, moving to a GitHub-based workflow helps us to be closer aligned to our development teams and to better facilitate collaboration. With our docs in a GitHub Enterprise repository, we can do documentation reviews using pull requests in the same way that engineers do code reviews.

Using Jenkins in our build process

We used Jenkins to automate our testing and build processes. When a pull request is created by an author, Jenkins automatically runs a check to confirm that the site is able to be built. A reviewer then reviews the pull request and merges it into the master branch if there are no issues. This triggers Jenkins to run another script which builds and deploys the Middleman site to our beta environment. After a final confirmation on beta, the site is deployed to our production server.

Docs-as-code approach

By using a static site generator, we are able to adopt a Git workflow for developing documentation which is similar to what other engineers use. This approach has helped our writers work more closely with our development teams. And we hope that with this increased visibility of our repository, we'll be able to further encourage engineers within the company to collaborate and contribute to our external-facing documentation. Ultimately, we think that this approach will allow us to iterate more rapidly on our site and develop higher quality documentation for our developers.

What's next

This is just a starting point for us in improving our developer documentation. For our next steps, we are looking to further automate processes to improve the quality of our docs and to push out new content even faster. This includes things like automating link validation, adding style linters, and automatically generating our API reference documentation. We will also add better search and navigation features on our site so that you can better find the content that you want.

In terms of content, we are looking to have more frequent releases and updates to keep you better equipped to create great apps using our developer products. We'll also be adding more ways for you to provide us with feedback so that we can provide you with a better developer experience. Stay tuned for those updates to come.

If you want to stay up-to-date with the latest news from the LINE Developers site, add the LINE Developers official account as a friend on LINE by scanning the QR code below.

Ending notes

If you are interested in hearing more about the technology behind the LINE Developers site, check out the following lightning talk from Mark Serrano, the technical lead on the documentation site, at our recent LINE Developers Day event.

Also, if you are passionate about creating quality documentation and improving the tool chain for documentation, we'd be happy to hear from you. For more information, check out the opportunities available at LINE at our careers page.

LINE Developers LINE Platform Technical writing Docs

Kenneth Lau 2017.11.07

Technical writer in charge of developer documentation for the LINE Platform

Add this entry to Hatena bookmark

Back to blog list