ドキュメントのレガシー化、忘れていませんか？ APIマニュアルWEB化までの経緯

こんにちは。kzhirata@QAです。連休が近づいてきましたね。
今年の2月から部署移動したせいか、今年は暦通り休めそうな気がします。
（何か最近、ブログ書いているのQAの人が多い気がする...）

今回はテストに関する話ではありません。
今までGoogleDocsからPDFを作成していたAPIドキュメントをGithub Pages上にWEB化したことについてお話しします。現在、まだ完成していないので実際のWEBページのURLはお見せできませんが、下記キャプチャでイメージを掴んでいただければと思います。

<現行のPDF>

<WEB化したキャプチャ>

現在、APIドキュメントは400ページ近くとなり、1つのGoogleDocsファイルにまとめきれなず、GoogleDocsのファイル数が10個以上となっています。
いわゆる「コードがレガシー」ならぬ「ドキュメントがレガシー」と化しています。
そんな状況で以前からAPIドキュメントをWEB化したいと強く思っていたのですが、簡単にMS Wordをmarkdownに変換するツール、およびmarkdownからHTMLを生成してくれるツールを見つけることができませんでした。

そんな中、今年の1月に上司のHさんから下記メールが届きました。

------------------------------------------
<上司のHさんからのメール内容>

https://github.com/blog/1939-how-github-uses-github-to-document-github
(Jekyllについて説明している記事でした。)

GitHubでどうやってドキュメント管理してるかのよさげな資料を見つけたので共有です。
参考まで
------------------------------------------

Jekyllは、Rubyで書かれたmarkdownから静的HTMLを作成するジェネレーターです。
日本では企業より、個人がブログで使っている人が多いなぁという印象です。
Github PagesもJekyllと同じ仕組みでHTMLを表示しています。
本家サイト、日本語サイトも充実しています。
私は、ドットインストールでJekyllの簡単な操作方法を覚えました。

はじめは「どーせ使いモノにならないだろうなぁ」と流し読みしていました。

なぜなら、Jekyllを試す前にいろいろなツールを試しましたが、運用含めてうまく行く気がしなかったからです。以下、過去に試した失敗です。

1. pandoc

htmlやdocx(MS Word)から、markdownに変換するときに真っ先に思いついたのがpandoc。
しかし、実際にやってみるとtable部分の変換がうまくいかず、この段階であきらめました。

2. sphinx

テーブルをちょっと修正しただけで、エラーとなってしまいます。
APIドキュメントはテーブルが非常に多いので、テーブルの要素をシンプルに記述できることが必要条件です。
これだと、開発者がrstファイルを修正してもデザインが崩れるといった状態となり運用が廻らないと思い断念しました。

pandocもsphinxも非常にすばらしいツールなのですが、APIドキュメントをmarkdown化するには、イマイチでした。
他に、下記ツールを試してみましたが、いずれも似たり寄ったりで使うにはハードルが高すぎました。

HTML-WikiConverter (perl)
kramdown (ruby)
Markdown Extra (PHP)
MarkdownJ Core (Groovy)
Knockoff (Scala)
Actuarius (Scala)
Markdown-js (Node.js)

結局、google docのtableのみ1つずつコピーして、google docスプレッドシートのセルの内容をGoogle Apps Scriptでmarkdownに展開するScriptを書いてmarkdownファイルに出力するという人海戦術をとりました。隙間時間しか使えなかったので2ヶ月かかりました...トホホ
（すみません。技術者らしくなくて...）

上記テーブル含めAPI1つにつき1ファイルをAPIのパスに従って構成したディレクトリ配下にmarkdownとして配置しました。

プレビューは、atomエディタを使うと便利です。
「Packages」→「Markdown Preview」→「Toggle Preview」でGithubとほぼ同じプレビューをリアルタイムで確認できます。

Jekyllの「_config.yaml」の設定は以下のようにしています。

 
markdown: redcarpet
redcarpet:
  ["hard_wrap","tables","no_intra_emphasis","with_toc_data"]

markdownは、githubと合わせるためにredcarpetを使っています。
これによって、gheリポジトリに表示されるものとWEBと整合性がとれます。
githubとの整合性をとらないのであれば、kramdownなど他の形式でもいいと思います。

GithubMarkdown同様、「```」でコードを囲うだけでシンタックスハイライターのデザインを下記のようにHTMLで表現できるのも魅力的です。

 
```xml
ValueA
ValueB
```

<実際のXMLコードのGithubの画面>

<上記Github画面に相当するJekyllの画面>

いい感じに対応してますね。

一方、「Jekyll使えそう」と思いたったのと同時に、単にWEB化して公開しただけでは、恐らく誰も使ってくれないと思い、まずは課題を整理しました。

OSSのツールいろいろあるけど、実際に仕事で使ってもらえるまでのハードルが非常に高いことは常々感じています。（だからお金払う商売が成り立つんでしょうけど。）

★「そもそもの課題」って何？

「PDFのマニュアルの課題と対処案」

【ドキュメント利用者】

ページ数が多いため、ファイルを開くまでが重い。（ファイルサイズ5MB以上）
更に該当する箇所を検索するのが面倒（「ctrl + f」でキーワード検索）
→ WEB化して、目的の情報を簡単に検索できるようにしたい。
→ 全文検索は必要

【ドキュメント作成者（開発者）】

- google docsは、内容だけでなく、フォント・罫線の調整に手間がかかる。
→ シンプルなフォーマットで編集できるようにしたい。
テキストデータ（コンテンツ）で構成管理したい。差分が分かりやすくしたい。github使えばレビューも手間がかからない。
- docsを結合して、目次追加し、WORDで保存。PDF化という作業が面倒。
→ テキストデータからプログラムを起動して自動でPDFを生成する。

文書をドキュメント化するにあたって、下記原則があるのではと思います。

シンプルなフォーマットを複雑にすることは簡単
複雑なフォーマットをシンプルにすることは困難

大事なことは、コンテンツとデコレーションを分離し、コンテンツのみを標準のフォーマット（できればテキスト形式で差分が簡単にわかるもの）で維持管理していくことではないでしょうか。

気が向いたら、次はGithub Pages上でAPIドキュメントの全文検索をどう実現したのかについて、書こうと思います。
（気が向かなかったら...すみませんm(_ _)m）

P.S. QAエンジニアはこちらで募集してます！我こそはと思う方、ぜひ応募してください！

SHANON Engineer's Blog