Transloadit における文章の品質管理の自動化
この記事では、2015年当時の公開ワークフローを紹介します。以下のパッケージ名と設定は当時のもので、現在のツールチェーン向けのインストール手順ではありません。
Transloadit で文章チェックを自動化した方法について、社内向けのドキュメントを書いていました。途中で、これは社外の皆さん 🌎 にも役立つのではないかと思い、より一般的な内容に書き直しました。まず課題の全体像を説明し、それから解決に必要な細部まで掘り下げていきます。楽しんでいただければ幸いです。それでは始めましょう!
Transloadit では、ある程度の分量がある文章(ドキュメント、ブログ記事、静的ページ)をすべて、独立したコンテンツリポジトリに切り出してきました。
この移行以前は、文章が MySQL のテーブル、テンプレート、HTML ファイルに散在していました。コンテンツ、レイアウト、コードがさまざまな場所で入り混じっていたのです。開発者ならすべてにアクセスできましたが、快適とは言えませんでした。開発者以外には手も足も出ませんでした。
そこで、テクニカルライターに参加してもらい、コンテンツへのフルアクセスを提供できないかと考えました。GitHub の Web インターフェースを wiki のように使えば、コードに気を取られたり、誤って変更したりせず、コードに詳しくなくても文章を改善できるのではないかと考えたのです。
まだ十分に活用できているわけではありませんが、次のような成果があります。
- 開発者である私たちは、すでに(Markdown だけで書かれた)コンテンツの編集を楽しんでいます
- すべてのコンテンツを別のリポジトリにまとめることで、品質管理の自動化、つまり継続的インテグレーションなど、ほかにも魅力的な可能性が広がります
継続的インテグレーション
継続的インテグレーションは、通常はコードに関連する概念です。ThoughtWorks では次のように説明しています。
継続的インテグレーション(CI)は、開発者が一日に数回、共有リポジトリにコードを統合する開発手法です。チェックインのたびに自動ビルドで検証することで、チームは問題を早期に発見できます。
Transloadit では、すでにすべてのコードにこの手法を使っていました。では、英語の文章にも使えないでしょうか?
これは私たちにとって特に重要な問いでした。お客様の大半は米国に住んでいますが、Transloadit はベルリンを拠点としており、現在のチームには英語を母語とするメンバーがいないからです。
製品を評価し始めた段階で文章の誤りが与える悪影響を考えると、追加のチェックを設けることは私たちにとって一層重要です。
コンテンツの品質改善に向けて、次の三つの領域に取り組んでいます。
配慮に欠ける表現
npm weekly から引用します。
コミュニティの仲間を排除したり傷つけたりするつもりは、おそらく誰にもないでしょう。それでも、対立を招く表現や特定のジェンダーを優遇する表現は、文章に紛れ込みがちです。別の視点で読み直し、見落としに気づき、より配慮のある包摂的な表現へと導いてもらえると、とても助かることがあります。Alex は、不快感を与えるおそれのある表現を見つけ、有用な代替表現を提案することで、「無神経で配慮に欠ける文章を見つける」のに役立ちます。
alex のインストールは、npm install --save alex を実行するだけです。
Alex は人間ほど賢くはありませんが、精いっぱい働きます。ただし、無神経かもしれない表現を、ときには張り切りすぎるほど指摘してきます。
つまり、ときには誤検知もあります。alex の警告で処理を失敗させたくないので、次のようにしています。
node_modules/.bin/alex || true
こうすれば、alex が改善できると判断した表現を確認しつつ、その提案を必須の修正にはせずに済みます。
たとえば、次のような結果になります。
74:74-74:76 warning $(he) may be insensitive, use $(they), $(it) instead
このプロジェクトのおかげで、現在はドキュメントをより包摂的な表現に書き直しています。
書式の乱れ
テキストファイルには Markdown 形式を使っています。選んだ理由は次のとおりです。
- 人間にもコンピューターにも比較的読み取りやすい
- 周辺ツールのエコシステムが充実している
- 文書の構造とレイアウトを適切に分離できる。強調する箇所は指定できますが、Comic Sans の指定はできません。そうした判断はデザイナーに任せます
Markdown では、同じ目的を達成する方法が複数あることもよくあります。コードと同様に、規約を決め、すべての貢献者に従ってもらうと役立ちます。この(無用な)表現の自由を少し制限すれば、文書がきちんと管理されているように見え、さらなる貢献にもつながります。
このために、mdast と lint プラグインを使っています。npm install --save mdast mdast-lint
外部プロジェクト(mdast 自体など)のチェックや、ビルド成果物の再チェックは不要なので、いくつかの場所を除外しています。
printf '%s\n' '_site/' 'node_modules/' >> .mdastignore
次に、以下の規約を .mdastrc に保存しました。もちろん、内容は各自の設定や
lint の好みによって変わります。
{
"plugins": {
"lint": {
"blockquote-indentation": 2,
"emphasis-marker": "*",
"first-heading-level": false,
"link-title-style": "\"",
"list-item-indent": false,
"list-item-spacing": false,
"no-shell-dollars": false,
"maximum-heading-length": false,
"maximum-line-length": false,
"no-duplicate-headings": false,
"no-blockquote-without-caret": false,
"no-file-name-irregular-characters": true,
"no-file-name-outer-dashes": false,
"no-heading-punctuation": false,
"no-html": false,
"no-multiple-toplevel-headings": false,
"ordered-list-marker-style": ".",
"ordered-list-marker-value": "one",
"strong-marker": "*"
}
},
"settings": {
"gfm": true,
"yaml": true,
"rule": "-",
"ruleSpaces": false,
"ruleRepetition": 70,
"emphasis": "*",
"listItemIndent": "1",
"incrementListMarker": false,
"spacedTable": false
}
}
続いて、初めて lint を実行します。
node_modules/.bin/mdast --frail .
次のような結果が返ることがあります。
_posts/2015-09-15-spelling.md
246:1 warning Use spaces instead of hard-tabs no-tabs
さらに、mdast は自動修正を試みることもできます。
node_modules/.bin/mdast --output .
mdast が修正できる範囲の広さには感心しました。ただし、このコマンドを実行する前に、必ずファイルを Git にコミットしてください。変更内容を確認し、必要なら元に戻せるようにしておきます。満足のいく状態にするには、おそらく何度か繰り返す必要があります。
スペルミス
Oxford University の Oxford Internet Institute 所長 William Dutton は、スペルミスによるオンライン売上の損失は「数百万」にという記事で、Facebook など、インターネット上のくだけたやり取りの場では、スペルや文法への許容度が高いと述べています。
しかし、ホームページや商用の商品・サービスなど、友人同士のやり取りではない場面では、信頼性や信用に対する懸念が生じます。そうした場合、単語のスペルミスが致命的な問題になりかねません。
「懸念」と聞いただけで、対策する気になりました。さっそく取りかかりましょう。Markdown 文書のスペルチェックには、npm install --save markdown-spellcheck を使っています。
文法や、「it's」と「its」の違いをはじめとする細かな点は見逃すかもしれません。それでも、私がしつこく繰り返してしまう困った間違いの多くを、本番に出る前に検出できます。
- 自分で作り出した英語(「symbiose」と「symbiosis」)
- 何度も繰り返すタイプミス(「editted」と「edited」)
- イギリス英語とアメリカ英語の混在(「summarise」と「summarize」)
(弁解すると、英語は母語ではありません 😄)
Markdown-spellcheck は、コードブロックなど Markdown 特有の要素も自動でスキップします。ただし、Transloadit や FFmpeg などは、やはり手動で除外する必要がありました。
printf '%s\n' 'Transloadit' 'FFmpeg' >> .spelling
これで Markdown ファイルのスペルミスをチェックする準備が整いました。
node_modules/.bin/mdspell \
--report \
--en-us \
--ignore-numbers \
--ignore-acronyms \
**/*.md \
_layouts/*.html \
_includes/*.html \
*.html
「editted」は単語ではない、という結果が返るかもしれません。
初回実行
初回の実行では、文書と辞書の両方に多くの問題が見つかる可能性があります。そのため、mdspell を --report フラグなしで実行し、デフォルトの対話モードに入るのがおすすめです。

このモードでは、特定のファイルを除外したり、.spelling 内に独自の辞書を作成したりできます。おそらく時間はかかりますが、いまひとつ気分が乗らない午後でも、生産的に過ごしたいときにはぴったりの作業です。
新しいコンテンツを追加する際には、許可リストにも単語の追加が必要になることがあります。それでも、辞書にない単語はすべて意図して使ったものだとわかります。それは気持ちのよいものです。
組み合わせ
では、ここまでのツールをまとめましょう。
これらのツールはすべて npm からインストールしたので、npm run スクリプトを使うのも合理的でしょう。ただ、今回は Makefile を選びました。単にシェルの自動補完で TAB キーを使うのが好きだからという理由と、Node.js、Bash、Go のどれで書かれていても、すべてのプロジェクトで開発者向けの操作の入口を統一したかったからです。
SHELL := /usr/bin/env bash
tstArgs :=
tstPattern := **/*.md _layouts/*.html _includes/*.html *.html
.PHONY: fix-markdown
fix-markdown:
@echo "--> Fixing Messy Formatting.."
@node_modules/.bin/mdast --output .
.PHONY: test-inconsiderate
test-inconsiderate:
@echo "--> Searching for Inconsiderate Writing (non-fatal).."
@node_modules/.bin/alex $(tstArgs) || true
.PHONY: test-spelling
test-spelling:
@$(MAKE) test-spelling-interactive tstArgs=--report
.PHONY: test-spelling-interactive
test-spelling-interactive:
@echo "--> Searching for Spelling Errors.."
@node_modules/.bin/mdspell \
$(tstArgs) \
--en-us \
--ignore-numbers \
--ignore-acronyms \
$(tstPattern)
.PHONY: test-markdown-lint
test-markdown-lint:
@echo "--> Searching for Messy Formatting.."
@node_modules/.bin/mdast --frail $(tstArgs) .
.PHONY: test
test: test-inconsiderate test-spelling test-markdown-lint
@echo "All okay : )"
これで make test を実行し、すべてのチェックに合格するか確認できます。
スペルミスだけを確認するには make test-spelling を実行できます。辞書にまだ載っていないと思われる新しい単語を多く含む文章を書いた後なら、make test-spelling-interactive で対話モードに入れます。
Bash Completion を利用している場合は、make と入力して TAB キーを押すだけで、利用できるすべてのショートカットを確認できます。
自動化
テストの自動化には、継続的インテグレーションのサーバーが必要です。
Travis CI、Strider、Drone.io は、いずれも要件を満たします。リポジトリに変更があるたびに、確実かつ再現可能な形でコードを実行できる、一元化された場所があればよいのです。
私たちは非公開プロジェクトに Jenkins を使っており、コンテンツリポジトリ向けに、連鎖して実行する三つのジョブを新たに作成しました。
content-buildは Jekyll で Markdown を静的 HTML コンテンツに変換し、次を起動しますcontent-testはこの記事のすべてのコマンドを実行し、次を起動しますcontent-injectは Web サイトに HTML を保存し、続いてwebsite-build、website-test、website-deployを起動します。これは、Web サイトのデプロイ用にすでに構築していた処理の連鎖です

これで、すべてのチェックに合格した場合にのみ、新しいコンテンツを取り込んでデプロイできます。かなり長い処理の連鎖ですが、幸いにもマシンが面倒を見てくれます。😄
また、マシンが新しいコンテンツの誤字を検出すると、すぐに通知が届くよう Slack 連携も設定しています。

これで完璧になったのか?
いいえ。人間は間違えますし、人間が作るマシンや辞書も同じです。
これからも .spelling の調整は必要ですし、「辞書」にも私の間違いを直してもらう必要があります。それでも、この文章の品質管理の自動化によって、互いにチェックし合い、以前より誤りを減らせています。
Transloadit では、初回の実行で 151件の誤りを修正できました。

そうです。私たちは本当にスペルが苦手ですでした!
今後に向けて
ビルドの処理チェーンに追加できそうな、ほかの便利な Markdown 処理ツールをご存じでしたら、Twitter または HN のコメントで教えてください。
最後に、文章の改善を手伝ってくれる優れたテクニカルライターを、引き続き探しています。コンピューターだけでは、できることに限りがありますから。😄
作業するのは Markdown ファイルだけで、それ以外は自動処理に任せられます。興味がありましたら、メールでご連絡ください!
