最近のアップデート
Cloud Automatorのアップデートでログイン中の操作画面にマニュアルのリンクが表示されるようになりました。
もちろんマニュアルだけでも閲覧できますので、気になった方は無料トライアルでCloud Automatorを試してみてください。
Cloud Automator– 株式会社サーバーワークス サポートページ
https://support.serverworks.co.jp/hc/ja/categories/115001305127
ドキュメントを充実させるには
ドキュメントを充実させていくには、地道に書いていくしかないわけで・・・Cloud Automatorについても開発メンバーで分担しながら作っています。
その際ちょっと気になってくるのが表記のゆれです。
これは多人数でなくても１人で書いていても、書いている時期が異なると表現が異なるとかありますしね。
細かい言い回しならそこまで気にする必要もなさそうなのですが、Cloud Automatorの使い方や機能を説明していくと当然ながらAWSについても言及する必要が出てきます。
AWS用語で表記のゆれが出てしまうとユーザーは気になりますし、検索する場合にヒットせず困ることも出てきそうです。
そこでAWSの公式ドキュメントに載っている日本語のAWS用語を利用して、表記のゆれをチェック行ってみます。
アマゾン ウェブ サービス : AWSの用語集
https://docs.aws.amazon.com/ja_jp/general/latest/gr/glos-chap.html
ツールを探してみる
表記のゆれをチェックできるツールとして知っているのは以下2つ。
今回は対象のファイルがMarkdownファイルであるのと、手元で手軽に動かしたたいので、npmでインストールできるtextlintを利用してみます。
また、prh形式のYAMLでルールを指定できるように次のツールも利用してみます。
ルールを作ってみる
チェックを行うためにはルールを作る必要があります。
AWS用語については公式にドキュメントとしてまとまっているので、これを利用するために次のような簡単なコマンドラインツールをgolangで作ってみました。
できることは単純で、日本語のAWS用語ページをスクレイピングしてprhで使える形式のYAMLファイルを出力します。
詳細はGitHub上のREADME.mdファイルを参照してください。
スクレイピングにはgoqueryというgolangの便利なライブラリを利用しています。
実際のYAMLファイルを見てもらえば分かりますが、単純に用語をそのまま抜き出しているものと、半角スペースで分解して単語単位で抜き出してものがあります。
たとえば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を利用してチェックできるようになりました。
しかし、実際にドキュメントを書く作業をしてみるともうちょっと便利にできそうな感じがするので試してみることにします。
私の場合ドキュメントを公開するまでに、
Markdown形式でドキュメントを書く。textlintでチェックし、修正があればなくなるまで繰り返す。Zendesk Guideにドキュメントを反映するためにMarkdown形式からHTML形式に変換する。Zendesk GuideにHTML形式でドキュメントを反映し、画像の追加や装飾などを行う。- チームメンバーにレビューをしてもらい、指摘があればなくなるまで修正を繰り返す。
の定型作業を行っているので、この作業を効率化したいわけです。
最終的にはZendesk GuideにHTML形式で記載することになります。
ですので、最初からHTML形式で書く方が効率的なの気もしますが・・・
個人的にはMarkdown形式の方が書きやすいので、Zendesk GuideがMarkdownに対応してくれるとうれしいなぁー
と言っても、そこはどーにもならないので次のような簡単なコマンドラインツールをgolangで作ってみました。
できることは単純で、Markdown形式からHTML形式に変換できます。加えて、この変換作業の前後で任意のコマンドを実行できるので、今回はtextlintを実行する形にしています。
ただし、textlintは別のプログラムなので事前にtextlintのインストールや設定は必要となります。
詳細はGitHub上のREADME.mdファイルを参照してください。
Markdown形式からHTML形式への変換にはblackfridayというgolangのライブラリを利用しています。v2への移行が進んでいますが、今回利用したのはv1になります。
出力するHTMLファイルにclassを動的に追加したいなら、v2に追加されたParseを利用して実現できそうな気がします。時間ができたら要確認かなぁ。
また、何度もチェックして変換する工程を繰り返すことが予想されるので、fsnotifyというgolangのライブラリを利用して、ファイルの変更検知をできるようにしてあります。ファイルの変更を検知してチェックと変換を繰り返し実行します。
CLI化するのには有名なので説明不要だと思われるcobraというgolangのライブラリを利用しています。
作ったものを使ってみる
せっかく作ったので使ってみるわけですが、前述したとおり変換前と変換後に外部コマンドを実行できます。
今回は変換前に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へ積極的にフィードバックしておきましょう！そのうちきっと修正してもらえるハズ
アマゾン ウェブ サービス : AWSの用語集 - EBSbacked
https://docs.aws.amazon.com/ja_jp/general/latest/gr/glos-chap.html#EBSbacked
Zendesk GuideにMarkdown形式が追加されてほしい- そー考えるとHatena Blogすごい書きやすいんだなーとあらためて思った
- golangは相変わらず便利、そしてちょー楽しい
blackfridayはv2を使っていないので今後使ってみたいfsnotifyは便利だったので今後も使っていきたい- 当然このblogも
Markdownで書いているのでtextlintを使ってチェックした
以上になります。