textlintを使ってAWS用語をチェックしてみる #aws #textlint #golang

最近のアップデート

Cloud Automator のアップデートでログイン中の操作画面にマニュアルのリンクが表示されるようになりました。

blog.serverworks.co.jp

もちろんマニュアルだけでも閲覧できますので、気になった方は無料トライアルでCloud Automator を試してみてください。

Cloud Automator – 株式会社サーバーワークス サポートページ
https://support.serverworks.co.jp/hc/ja/categories/115001305127

cloudautomator.com

ドキュメントを充実させるには

ドキュメントを充実させていくには、地道に書いていくしかないわけで・・・Cloud Automator についても開発メンバーで分担しながら作っています。

その際ちょっと気になってくるのが表記のゆれです。 これは多人数でなくても1人で書いていても、書いている時期が異なると表現が異なるとかありますしね。

細かい言い回しならそこまで気にする必要もなさそうなのですが、Cloud Automator の使い方や機能を説明していくと当然ながらAWSについても言及する必要が出てきます。

AWS用語表記のゆれが出てしまうとユーザーは気になりますし、検索する場合にヒットせず困ることも出てきそうです。

そこでAWSの公式ドキュメントに載っている日本語のAWS用語を利用して、表記のゆれをチェック行ってみます。

アマゾン ウェブ サービス : AWS の用語集
https://docs.aws.amazon.com/ja_jp/general/latest/gr/glos-chap.html

ツールを探してみる

表記のゆれをチェックできるツールとして知っているのは以下2つ。

github.com

github.com

今回は対象のファイルがMarkdownファイルであるのと、手元で手軽に動かしたたいので、npmでインストールできるtextlintを利用してみます。

また、prh形式のYAMLでルールを指定できるように次のツールも利用してみます。

github.com

ルールを作ってみる

チェックを行うためにはルールを作る必要があります。

AWS用語については公式にドキュメントとしてまとまっているので、これを利用するために次のような簡単なコマンドラインツールをgolangで作ってみました。

github.com

できることは単純で、日本語のAWS用語ページをスクレイピングしてprhで使える形式のYAMLファイルを出力します。

詳細はGitHub上のREADME.mdファイルを参照してください。

github.com

スクレイピングにはgoqueryというgolangの便利なライブラリを利用しています。

github.com

実際のYAMLファイルを見てもらえば分かりますが、単純に用語をそのまま抜き出しているものと、半角スペースで分解して単語単位で抜き出してものがあります。

github.com

たとえばAmazon Simple Workflow Serviceを登録する場合、

 - expected: 'Amazon Simple Workflow Service'
 - expected: 'Amazon'
 - expected: 'Simple'
 - expected: 'Workflow'
 - expected: 'Service'

の5種類を登録しています。

これは実際にチェックする際により多くのパターンにマッチさせたかったためで、利用してみてマッチしすぎる場合は必要のない部分を削除して使う形にしました。

作ったルールを利用してみる

作ったルールを実際に利用するには.textlintrc というtextlintの設定ファイルに、作成したaws_words.ymlファイルのパスを記載するだけです。

{
  "rules": {
    "prh": {
      "rulePaths": [
        "./aws_words.yml"
      ]
    }
  }
}

試しに次のようなMarkdownファイルに、上記の設定でtextlintを実行すると、

# AWS用語のチェック

- awsはダメ。
  - Amazon Web Serviceも間違い。
  - 日本語なので正解はアマゾン ウェブ サービス。

- 同じくAWS Management Consoleは英語なのでダメ。

のような結果になり、ルールにしたがってチェックされていることが確認できます。

$ textlint test.md

/Users/uchimanajet7/self-work/github/awr/test.md
  3:3   ✓ error  aws => AWS                                            prh
  4:5   ✓ error  Amazon Web Service => アマゾン ウェブ サービス        prh
  4:5   ✓ error   => Amazon                                            prh
  4:7   ✓ error  違い => AZ                                            prh
  4:16  ✓ error  ェブ サービス => service                              prh
  4:16  ✓ error  service => Service                                    prh
  7:6   ✓ error  AWS Management Console => AWS マネジメントコンソール  prh
  7:6   ✓ error  でダメ => AWS                                         prh
  7:10  ✓ error  同じくAWS マネジ => Management                        prh
  7:21  ✓ error  ントコンソール => console                             prh

✖ 10 problems (10 errors, 0 warnings)10 fixable problems.
Try to run: $ textlint --fix [file]

いくつか余計と思われる部分が指摘されていますが、これはルールを機械的に作り出しているために起こっているので、取り除きたい場合にはルールのaws_words.ymlファイルを編集します。

もうちょっと便利に

これでMarkdownファイルに書かれている内容について、なんとなくですがtextlintを利用してチェックできるようになりました。

しかし、実際にドキュメントを書く作業をしてみるともうちょっと便利にできそうな感じがするので試してみることにします。

私の場合ドキュメントを公開するまでに、

  1. Markdown形式でドキュメントを書く。
  2. textlintでチェックし、修正があればなくなるまで繰り返す。
  3. Zendesk Guideにドキュメントを反映するためにMarkdown形式からHTML形式に変換する。
  4. Zendesk GuideHTML形式でドキュメントを反映し、画像の追加や装飾などを行う。
  5. チームメンバーにレビューをしてもらい、指摘があればなくなるまで修正を繰り返す。

の定型作業を行っているので、この作業を効率化したいわけです。

最終的にはZendesk GuideHTML形式で記載することになります。 ですので、最初からHTML形式で書く方が効率的なの気もしますが・・・ 個人的にはMarkdown形式の方が書きやすいので、Zendesk GuideMarkdownに対応してくれるとうれしいなぁー

www.zendesk.co.jp

と言っても、そこはどーにもならないので次のような簡単なコマンドラインツールをgolangで作ってみました。

github.com

できることは単純で、Markdown形式からHTML形式に変換できます。加えて、この変換作業の前後で任意のコマンドを実行できるので、今回はtextlintを実行する形にしています。

ただし、textlintは別のプログラムなので事前にtextlintのインストールや設定は必要となります。

詳細はGitHub上のREADME.mdファイルを参照してください。

github.com

Markdown形式からHTML形式への変換にはblackfridayというgolangのライブラリを利用しています。v2への移行が進んでいますが、今回利用したのはv1になります。

github.com

出力するHTMLファイルにclassを動的に追加したいなら、v2に追加されたParseを利用して実現できそうな気がします。時間ができたら要確認かなぁ。

また、何度もチェックして変換する工程を繰り返すことが予想されるので、fsnotifyというgolangのライブラリを利用して、ファイルの変更検知をできるようにしてあります。ファイルの変更を検知してチェックと変換を繰り返し実行します。

github.com

CLI化するのには有名なので説明不要だと思われるcobraというgolangのライブラリを利用しています。

github.com

作ったものを使ってみる

せっかく作ったので使ってみるわけですが、前述したとおり変換前と変換後に外部コマンドを実行できます。

今回は変換前にtextlintを実行してAWS用語のチェックを行い、変換後にはHTMLを実行環境のデフォルトブラウザで表示してレイアウトの確認を行います。

設定ファイルには次のように実行するコマンドと置換する文字列を記載してあります。

{
    "Page": true,
    "CSS": "style.css",
    "PreCommands": [["textlint", "%INPUT_PATH%"]],
    "PostCommands": [["open", "%OUTPUT_PAGE_PATH%"]],
    "ReplaceTexts": [
        "<blockquote",
        "<blockquote class=\"is-colored\"",
        "<ol",
        "<ol class=\"list-colored\"",
        "<img",
        "<img class=\"image-with-border\"",
        "<table",
        "<table class=\"table table--bordered table--color-header\""
    ]
}

これで変更検知をする次のコマンドを実行して、ドキュメントを更新するとtextlintを実行して変換後のファイルを実行環境のデフォルトブラウザで表示できているはずです。

現状は変化前、変換後のコマンド実行でエラーがあってもそのまま実行を続ける仕様ですので、textlintで指摘があってエラーが表示されていても実行は継続します。

また、openコマンドでデフォルトブラザを開いているだけですので、ブラウザが複数立ち上がるってしまう可能性があります。

まとめ

  • textlintを使って表記のゆれをチェックできる
  • 人のレビューを受ける前に機械的にチェックできるのはありがたい
  • 頑張ってprh形式のYAMLファイルを用意すれば、任意のルールでチェック可能
  • AWS用語は公式サイトにまとめられているので利用できる
  • ただし、日本語へのローカライズで問題ありそうな文言もあるので注意が必要
  • あと、誤表記やTypoを発見したらAWSへ積極的にフィードバックしておきましょう!そのうちきっと修正してもらえるハズ

f:id:uchimanajet7:20171016000127p:plain

アマゾン ウェブ サービス : AWS の用語集 - EBSbacked
https://docs.aws.amazon.com/ja_jp/general/latest/gr/glos-chap.html#EBSbacked

  • Zendesk GuideMarkdown形式が追加されてほしい
  • そー考えるとHatena Blogすごい書きやすいんだなーとあらためて思った
  • golangは相変わらず便利、そしてちょー楽しい
  • blackfridayはv2を使っていないので今後使ってみたい
  • fsnotifyは便利だったので今後も使っていきたい
  • 当然このblogもMarkdownで書いているのでtextlintを使ってチェックした

以上になります。