Onsen UIのドキュメントの話

DevRel Meetup in Tokyo #23

Masa Tanaka

田中 正裕 <masa@monaca.io>

MASA TANAKA

Founder, Asial Corporation

Head of product development, Monaca & Onsen UI

Tokyo, Japan

@massie

masahirotanaka

Onsen UI

  • HTML5製のモバイルUIフレームワーク
  • Web Componentsをベースにしています
  • iOS, Androidをサポートしています
  • オープンソース(Apache 2 License)です

ハイブリッドアプリ、PWA用

UIフレームワーク

Operating System

WebView

Your App in HTML5

インターナショナルなチーム

anatoo

asial-matagawa

frankdiox

misterjunio

日本語メンバー

英語メンバー

日本語と英語の両方で記述

国外ユーザーがトラフィックの85%

  • 8月セッション数: 約10万

本日の話

  • ユーザーの体験について
  • ドキュメント執筆の進め方
  • 作成における課題

誘導したい流れ

GitHubの

README

Webサイト

のLP

  • 製品の概要とメリット
  • ユースケース
  • ガイドへの導線
  • 製品の概要
  • ガイドへの導線
  • ソースコードの説明

ドキュメント

(ガイド)

 

リファレンス

 

 

チュートリアル

 

製品の理解

導入

活用

活用に進めるための必要事項を記述

README.md

重要ポイント①:1行説明を詳しく書く

重要ポイント②:画像を多く配置(アニメGIF)

ランディングページ

検索エンジンからのアクセス用。

誘導先は「サンプル」と「Get Started」の2つ。

ガイド

検索エンジンからのアクセス用。

「サンプル」と「Get Started」の2つ。

ガイドの構造

  1. 導入(ESSENTIALS)
    1. インストール
    2. Getting Started
    3. FAQ
  2. フレームワークとの組合わせ
  3. 補足事項を深掘り

改善プロセス

  • ドキュメントの問題点を洗い出す
    1. チーム内のフィードバック
    2. 新しく入ったメンバーに先入観なしで見てもらう
    3. SEOやナビゲーションといったテクニカルな側面も

 

  • ユーザーの体験を考えてガイドの骨子を策定
    • Onsen UIの場合は「キホン」「フレームワーク」「高度」の3つに分離
    • キホンを読み終わったらリファレンスを見て自分で使いこなせられることを期待

 

  • 全員でコラボレーションしながら文章を執筆する

フィードバック/問題点

改修案

  • どんな製品かを、メリットと共に簡潔に説明
  • 図をもっと増やす一方、文章は少なめに
  • 難解、テクニカルな言葉は使わない
  • ビデオによる解説がない
  • まずは骨子を作成
  • 各ページの目的を定義
  • 3パート構成に

チーム全員で協力して作成

  • 他の類似製品のドキュメントを参考に
  • 構文チェッカー(Grammerly等)導入
  • ネイティブチェックを依頼
  • 英語ファーストで執筆

イントロビデオの作成

  • オフィス内にある簡易スタジオで録音
  • パワポのスライドを流すだけ
  • 導入セクションの内容を収録

CIで運用 / Transifexで翻訳

GitHub

 

onsen/onsen.io

CircleCI

AWS S3

Transifex

翻訳サーバー

コンテンツはMarkdownで執筆し、Metalsmithでジェネレート

CDN(KeyCDN)経由で配信

執筆はMarkdown

ローカライズはgettext

index.md

英語のコンテンツ

index.po

日本語の対訳DB

運用における課題

  1. 一方通行のローカライズによる弊害
  2. 日本語/英語ドキュメントの同期
  3. 改善効果を数値化しづらく、見えづらい
  4. Non-documentedな仕様を無くしていく

その他の施策

関連資料

国産OSS立ち上げの実情

〜Onsen UI が GitHub で5000スターを獲得するまでの道のり〜

ありがとうございました

Onsen UIのドキュメントについて

By Masa Tanaka

Onsen UIのドキュメントについて

DevRel Meetup in Tokyo #23での発表資料です。イベントのURL: https://devrel.connpass.com/event/64284/

  • 683
Loading comments...

More from Masa Tanaka