VS Code-textlint を使ってAnsible Role READMEの初期品質UP！

■ 概要

VS Code Meetup #3 でのLT内容詳細です。LTでは話していない内容も含まれています。

2020/2/19 のLT資料は「こちら」

■ textlint とは

　プログラミング言語にある lint と同じ考え方をテキストに対して行い、誤字脱字・助詞の重複・句読点のチェックなど文章の校正を支援するツールです。
日本人のazuさんが開発され、日本語テキストのチェックに強い点がポイントです。ネット検索すると分かるとおり広くテキストの品質向上に利用されています。

チェックできる例：

技術文書向けのtextlintルールプリセットに列挙されているチェック観点を転記します。

* 1文の長さは100文字以下とする
* カンマは1文中に3つまで
* 読点は1文中に3つまで
* 連続できる最大の漢字長は6文字まで
* 漢数字と算用数字を使い分けます
* 「ですます調」、「である調」を統一します
* 文末の句点記号として「。」を使います
* 二重否定は使用しない
* ら抜き言葉を使用しない
* 逆接の接続助詞「が」を連続して使用しない
* 同じ接続詞を連続して使用しない
* 同じ助詞を連続して使用しない
* UTF8-MAC 濁点を使用しない
* 不必要な制御文字を使用しない
* 感嘆符!！、感嘆符?？を使用しない
* 半角カナを使用しない
* 弱い日本語表現の利用を使用しない
* 同一の単語を間違えて連続しているのをチェックする
* よくある日本語の誤用をチェックする
* 冗長な表現をチェックする
* 入力ミスで発生する不自然なアルファベットをチェックする
* 対になっていない括弧をチェックする

なお、チェックを行うルールを自作することが可能です。プラグインを開発するタイプと、prh というプラグインに表記ゆれのルールを正規表現で追記していく方法があります。

■ textlint を何のために利用しているのか

　私が関与していたプロジェクトでは、数多くのAnsible Role の開発を実施していました。Ansible Role はその使い方をREADME として登録する必要があり、その文章チェックを効率的に実施するためにtextlint を利用することにしました。
所属する社内にはドキュメント執筆ルールがあり、その表記の揺れや漢字の使用・不使用などのパターンを容易に追加できることも利用する一つの理由になっています。

■ なぜ利用しているのか

　REAMDE ファイル自体には、書式のテンプレートを決めています。しかし、執筆する内容は開発するAnsible Role に依存するためリリース前に十分なレビュー実施が必要になります。
Ansible で動作するRole本体については、専用のツールを利用することでテストの自動化を行えるようになり、一定の品質を確保できるようになってきました。しかしREADMEファイルについては、人がチェックせざるを得ないため、開発するRole数が増えてくることでレビューアの負担が高くなってきました。

レビューアの負担が高まる理由は以下：

・レビュー対象の数が多い
・社内のSIで構築するソフトウェアの種類が多い
・文章品質を一定にすることは容易でない
・開発者の文章力にも依存する
・開発者が複数あり、国内外に分散している
・日本語能力が高い外国人開発者であっても、微妙な文章ニュアンスが表現できていないことがある

上記のようなレビューアの負担を少しでも軽減するためにtextlint を利用し、レビューを行うテキストのベースライン品質を整えるようにしました。

■ VS Code Extension を使う理由

　READMEのレビューを開始するベースライン品質を得るためtextlintを利用するようにしました。さらにVS Code 拡張機能を利用する理由は以下になります。

「Role開発とシームレス にREADME執筆も進められる」

単にVS Code を使うようにしただけではなく、開発のgit フローも整理し直しました。

VS Code textlint Extensions 利用前の作業の流れ

VS Code textlint Extensions 利用後の作業の流れ

■ textlint を利用した効果

レビューア
　内容のレビューに集中できる（textlint がチェックするような点を気にしなくて良い）

開発者
　つまらないtypo などを人から指摘されることがない（安心感）

■ 利用のポイント

① textlint は有益なルールが多数開発されています。実際のプロジェクトでは、どのようなルールを選択すべきかチームとして決めていく必要があります。場合によっては、自作をしましょう。

② 我々のように開発者が分散している場合、textlint のルールを整合していく必要があります。マージされたdevelopブランチで最終チェックを実施するルールがマスタとなるようにプロセスを明確にしていくと良いでしょう。

③ textlint は、VS Code以外でも利用できます。開発者のエディタ宗教戦争（意外と根深い問題）によっては、エディタを統一するのではなく、OUTPUTの品質重視でいった方がいいかもしれません。

■ まとめ

　プログラム言語とは異なり、テキストの内容を最終的に利用するのは「人」であるため、完全な自動チェックが難しいです。今後機械学習の発展によって、解析技術が進み、文章の意味までの自動チェックができるようになることは近いと思われますが、当面は人によるレビュー実施が必要でしょう。その中で、textlint で実施するベースラインの品質確保は開発効率化のポイントになると思っています。

■ リンク

https://github.com/textlint/textlint

textlint + prhで文章を校正する方法