ドキュメントとdocstringでGrammarly Premium使ったらとても良かった話

# TL;DR

- 3ヵ月ほど自作のPythonライブラリのドキュメントとdocstringの英語の執筆でGrammarly Premiumを使ってみたのでその所感などをまとめ記事です（利用は主にVS Code上）。
- Premium版契約前も半年程度無料版を使ってきています。
- チェックを通っているので変な英語を書いていない・・・という安心感が得られます。
- 即時のフィードバックや修正案の提示と反映などは英語執筆面で勉強になります。

# Grammarly Premiumってなに？

- 英文法や英語のtypo、読みにくくなっている英文の部分などを指摘してくれるサービスの有料版です（無料版もあります）。
- スタイルや英語圏（例 : アメリカ英語）などを設定しておいてそのスタイルで統一して書くこともできます（例 : アメリカ英語で統一して技術関係と設定したり等）。たとえば技術関係と設定して書いたりしていると曖昧な表現や受け身な表現になっていると怒られます。
- Premium版とかだと「こんな風に直すと良いよ」と提案もしてくれたりその提案を反映してくれたりもします。

詳しくは公式サイトWikipedia、以下の引用などをご確認ください。

https://www.grammarly.com/

> Grammarly（グラマリー）はアメリカの多国籍テクノロジー企業である。人工知能と自然言語処理を用いたデジタルライティングツールを開発している[5]。機械学習とディープラーニングのアルゴリズムを駆使した製品を通して、文法チェック・スペルチェック・盗用検出 のためのサービスを提供している。Grammarly のサービスは、提案機能も備えている。より意味を明瞭にするため、より簡潔な表現にするため、あるいは他の言葉や表現および言い回しを検討するための提案を行う。

https://ja.wikipedia.org/wiki/Grammarly

DeepLと並んで研究や技術界隈の方々もよく触れていらっしゃいます。

https://twitter.com/matsumotory/status/1483972533074665474?s=20&t=yMq6MIFGvgGzyRF059389w

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/228778/8c615f0b-6831-d56e-f901-6611246e03ee.png)

[※Songmuさんの変化し続けるキャリアと変わらない原体験 - 63スライド目から引用](https://junkyard.song.mu/slides/yapc-japan-online-2022/#63)

# 対象のライブラリとドキュメント

以下の趣味で作っていっている自作Pythonライブラリとドキュメントページで利用しています。

https://github.com/simon-ritchie/apysc

ドキュメントページ :

https://simon-ritchie.github.io/apysc/index.html

※コード内のdocstring（Pythonモジュール内のコードドキュメント）もチェック対象にしています。docstring自体はnumdoclintという自作LintでNumPyスタイルで内実に合わせて漏れなく書くように縛りを設けてあります。docstringについて詳しくは以下の記事などをご確認ください。

https://qiita.com/simonritchie/items/49e0813508cad4876b5a

https://qiita.com/simonritchie/items/84c4d4b2528309c30359

規模的にはCodeQLのGitHub Actionsなどを見ている感じPythonコードが数万行（10万行は一定無さそう）、ドキュメントページは本記事執筆時点で100ページ強程度だと思われます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/228778/ef1f80e0-af48-0b50-c51f-0d349b74d311.png)

# 利用環境

ドキュメントやdocstringの執筆を基本的にVS Code上でやっているのでGrammarlyも無料版のころからVS Code上で使っています。この辺はPremium版でも変わらずです。その辺は以下の記事に以前書いたので設定などはそちらをご確認ください。

https://qiita.com/simonritchie/items/f49943f08cd09b92f3f9

また、Pythonモジュール内のdocstringに関してはそのままだとチェック対象になりません（テキストファイルや.mdのマークダウンファイルなどならチェック対象となります）。そのためこの辺は自前でスクリプトを書いてマークダウンに置換される・・・みたいな処理がLintなどの諸々のチェックや変換を通す時に一緒に実行されるようにしてあります。

そのままdocstringのフォーマットで出力すると引っかかってしまうという点もあるので出力・同期するマークダウンではGrammarlyに合わせて出力するようにしてあります。

例えばdocstring中では`parameter : type`みたいな引数などの記述を多く使っていますが、そのままマークダウンで出力すると`parameter: type`みたいにコロンの位置を調整してね、といったエラーが出てしまうのでその辺のコロンの位置などを調整しています。

publicなAPIドキュメントに関してはダイレクトにドキュメントのマークダウンに反映される箇所も多いのでそのままチェックされる・・・といった形になっています（それらのドキュメントのビルドにはSphinx・ホスティングにはGitHub Pagesを使っています）。

# なによりも変な英語で世の中に出してしまっていないという安心感がある

残念ながら私は英語の執筆には自信が全然ありません。全然英語ができない人です。この辺は日本語で考えても義務教育だけでも9年間勉強し、そしてずっと日本語を日々浴びている・・・という状況を考えると言語の習得はかなり時間がかかるものだと思いそもそもレベルが低い状態は受け入れています（勉強はずっと続けますが）。

一方でOSS活動や自作ライブラリをGitHubで作って公開したりすると英語で色々ドキュメントなどを書いたりする必要が出てきます。このようなGitHub上での活動はとても楽しくのですが自身の書く英語が不安になることが今まで結構ありました（この英語で大丈夫なんだろうか・・・？といった具合に）。

そういった不安がGrammarly Premiumを通す形になってからは実際に多くの点でチェックに引っかかっており修正を色々加えていて、「Grammarlyで一通り通して修正済みなのだから最低限のところはOKでしょう・・・」と安心できるようになりました。気兼ねなく執筆・修正して日々デプロイしていっています。

# Grammarlyからのフィードバックはとても英語の勉強になる

よく勉強などでは頻繁なフィードバックを得られる状態が好ましいと言われます。

学生のころの勉強でも解いてみて答え合わせをしたり間違えていたら解説を読んだりといった点もそうですし、先生や講師の方から指摘をいただいたり、日々のプログラミングでもコンパイル（ビルド）エラーやランタイムエラーなどのエラーメッセージのフィードバックを得たり、コードレビューであったりペアプロやモブプロなどでのフィードバックなども学びがたくさん得られます。

一方でドキュメントなどの英文の執筆では中々フィードバックが得られません。有名ライブラリとかなら多くのContributorの方がいらっしゃって多くの目があるので得られるかもしれませんが趣味で書いている自作ライブラリなどだと中々issueやプルリクなどで英語のミスなどを指摘いただけません。

Grammarly Premiumを入れたことでこの辺のフィードバックがVS Code上でドキュメント執筆作業などをしていてリアルタイムに得られるようになりました。とても勉強になっていますし日々フィードバックを得て修正を加えるといったことを繰り返していることで段々と少しずつ引っかかる点が少なくなってきている感じはします。

また、無料版を使っていたころには警告などが出ても「どう直せばいいのだろう？」と感じるケースが結構ありましたが、Premiumだと迷った時などは自動で直してくれたりもする（且つ結構精度がびっくりする）ので自動修正後の英文と比較してどのように直せばOKなのかという点がさくっと分かって大分楽になり、そして勉強になっています。

※無料版を使っていたころにはその辺の理由に起因して警告までは修正せずにエラーのみ修正・・・としていたのですがPremiumにしてからは警告も一通り直せる箇所はなるべく直す方向で進めていっています（一部直すと技術文書の単語的に微妙になりそう・・・といった類のものは止むをえずでスルーしています）。

# 時間が経ってから後で直すのは結構しんどい

若干後悔したのですが、自作ライブラリでは結構実装が進んでドキュメントを量産してからGrammarly Premiumに切り替えました。切り替え後に一通りのドキュメントをチェックして直したり、docstringも一通りチェックされるようにしたり・・・としましたが（プライベートでちまちま対応しているというのもあり）終わるまで3か月というレベルで大分時間がかかりました。

Lintや自動テストなどと同様にこの手のものは早い段階で入れたり整備しておけば良かった・・・とちょっと後悔しています（自戒）。まあでも時間が経過すればするほどしんどくなってくるので現時点で一旦実装を止めがちにしてこれらの全体的な対応を入れて挫折せずに対応しきったのは良かったと思います。

# 後で確認して直さなきゃ・・・と思いつつ書くのはきつい

これも前節に似たような内容になりますが、Premiumを導入したりdocstringもチェックできる仕組みを入れる前は「今書いているものは将来チェックを通した色々引っかかって修正で二度手間になりそう・・・」と思いつつドキュメントやらを書いていました。

結構メンタル的にも宜しくないのでそういった意味でも早めに導入・整備しておけば良かったと感じました。

# デプロイ前にdocstringのチェックが走る安心感によって筆が進むようになった

今まではdocstringの英語で「この書き方で良いのだろうか？」とか思いつつちまちまネットで調べたりしつつ書いていっていましたが、今はデプロイ前に更新をかけたところを一通りチェックが入ったりができるようになっているので安心して雑に（？）英文を書けるようになったのでdocstringの執筆で悩むことが減った気がします。

「デプロイ前のチェックで引っかかったら直せば良いか・・・」という感覚でどんどん書いて進めても問題ない・・・というのは個人的にはとても快適です。

# docstringも結構typoや警告などが発生していた

前述の通りPythonモジュール内のdocstringは直接VS Code上のGrammarlyでチェックすることはできないため今まではGrammarlyでのdocstringのチェックをせずにたくさんの実装が追加されていました。

一方で後日docstringがチェックされるようになってからは多くのtypoが見つかったり恥ずかしい感じの文法ミスで引っかかったり、読みづらさの警告などが出たり・・・と色々宜しくない感じの英語になっていました（たくさん引っかかっていて修正は大変でした・・・）。

この辺のdocstringのコードに密に紐づいたドキュメントは個人的には非常に大切にしていますし、SNSなどでもこの辺の大切さは見かけたりしますし自分で記事を書いたりLintを作ったりしています（APIドキュメントとしても出力・同期していますし）。

https://twitter.com/kazuho/status/1491027036005023745?s=20&t=L4cHDz86C4Ejvj3rqlIoHw

しかしながら英語力の問題でdocstringの質があまり良くないのでは・・・という感じは今まで拭えず、docstringを重視している身からするともどかしい感じがありました。

この辺りも今ではきっちりチェックされるようになって来たので満足感が高くなっています。

# 一度一通り修正した後は快適に過ごせている

前述のように途中からPremium版を契約したり仕組みを整備したりした都合、最初のチェックと修正は大分茨の道となりましたが一度一通りチェックと修正が終わった後は（今のところ）日々のアップデート作業での少量のGrammarlyのチェックや修正などは大分楽です。

若干デプロイ前のチェックやLintなどが多くなりすぎて段々アップデートがきつくなってくるのでは・・・？と少し懸念していましたが（今のところは）特に大きく負担になることはなく過ごせており安心しました。

# docstringのマークダウンへの変換処理について

おまけ的に少しdocstringの変換などを扱ったスクリプトなどに関しても（長くなるのでリンク張る程度ですが）触れておきます。

※docstringのフォーマットはNumPyスタイルで統一してあるため変換処理もNumPyスタイル前提で書いてあります。

docstringのパース処理的なところ（概要やParameters、Returnsなどの要素の分割など）は主に以下のPythonスクリプトで行っています。

https://github.com/simon-ritchie/apysc/blob/main/apysc/_lint_and_doc/docstring_util.py

パースしたものを使ってGrammarlyチェック用に加工しつつマークダウンで保存する処理は主に以下のスクリプトで行っています。

https://github.com/simon-ritchie/apysc/blob/main/apysc/_lint_and_doc/docstring_to_markdown_converter.py

スクリプトを通すと同じパッケージ構成（apyscパッケージ以下）の各モジュールのdocstringの内容が以下のような感じでマークダウンで出力されるようになっています。

https://github.com/simon-ritchie/apysc/blob/main/docstring_markdowns/apysc/_geom/path_bezier_2d.md

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/228778/fbad1545-aba1-88b6-c577-8788d01ec5ca.png)

※前回変換時のハッシュ値を保持しておいて、その後に更新を検知したファイルのみ実行する形で日々の処理時間を短くしています。

# 余談

※規約やガイドラインなどを再読して問題なさそう・・・と判断していますが、この節の内容は不適切とご指摘をいただきましたら削除します。

---

記事と主題とずれますが、Grammarlyは元々Wikipediaにも書かれているようにウクライナ発のサービスとなります（現在は本社はアメリカのようですが、ウクライナにオフィスもあるようです）。

> Grammarly は、2009年に、ウクライナ人である Alex Shevchenko・Max Lytvyn・Dmytro Lider によって開発された。
> ...
> 2017年5月、同社は、最初の資金調達で1億1000万ドルを調達した。2019年10月、同社は、2回目の調達で9億ドルを調達し、企業評価額は10億ドルを超えた。ウクライナ発の初めてのユニコーン企業である。

https://ja.wikipedia.org/wiki/Grammarly

先日公開されていたメッセージの公開のお願いとしてのRubyコミュニティの方のgist然り、社員の方も大変な状態になっている方もいらっしゃるのではと思われます。

> どうか、ただメッセージを公開してほしい。どんなメッセージでもいい。Twitterで、メーリングリストで、自分のサイトのトップページで。きっと簡単だし、何もコストは掛からない。

[ハリコフのRubyistからRubyコミュニティへのお願い](https://gist.github.com/technohippy/465d2a28ebabf6c417f8ee88e23be463)

直近でGrammarlyのPremium版を年契約に切り替えたり、少額ながら大使館の口座へ寄付などさせていただきましたが、少しでもウクライナの方々の足しになると幸いです。1日でも早く戦争が終わり、ウクライナの皆様が平和に過ごせることを願っています。

# 参考サイト・文献まとめ

https://www.grammarly.com/

https://ja.wikipedia.org/wiki/Grammarly

[変化し続けるキャリアと変わらない原体験](https://junkyard.song.mu/slides/yapc-japan-online-2022/)

https://qiita.com/simonritchie/items/f49943f08cd09b92f3f9

https://qiita.com/simonritchie/items/49e0813508cad4876b5a

https://qiita.com/simonritchie/items/84c4d4b2528309c30359