textlintと音読でドキュメントをレベルアップする（ひとりレビューの方法）

2023年1月30日 05:44

先日レビューのコツについてnoteを書きました。

すると、「周りにレビューしてもらう人がいない」というご意見をいただきました。レビューは誰かにしてもらうことが良いですが、1人でもある程度はできるので、今回は1人でレビューする方法を紹介します。

textlintを利用する

textlintとは、校正ルールにもとづいて自動で文章の誤りを修正してくれるツールです。例えば、以下のように修正点を提示してくれます。

誤字脱字や文章の間違い、文章の長さを指摘してくれるのでとても助かります。
たくさんの校正ルールが用意されているので、ご自身でのスタイルに合ったルールを適用できますし、独自のルール作成もできます。

textlintの導入方法は、下記の記事をご参照ください。

校正ルールは下記を参考に設定してください。

利用方法としては、ローカルでコマンドを実行して利用する方法と、CIと連携して自動化する方法があります。

1人プロジェクトであればローカルで実行するで問題ないかと思いますが、毎回実行するのが面倒な場合は、CIと連携することでコミット時に自動でtextlintチェックができます。

音読することで、文章の違和感や読みにくい箇所を発見できます。書いている時には何も感じないのですが、声に出して読んでみると不思議と違和感出るのですよね。
また、第三者に読んでもらうことで、読めない/読みにくい漢字を発見できます。そこで漢字は開くべきか閉じるべきかを決定します。

自分で音読するのが面倒だという方は、音読ツールを利用して読んでもらうという手もあります。

音読には以下ツールが利用できます。

また、mediumでは音声読み上げの機能があります。

注意点
ツールによっては情報が保存される場合もあります。
機密情報は書かないようにするか、利用規約を読んでから利用することをおすすめします。

英訳すると日本語で表現したいことが伝わっていない場合があります。例えば、日本語だと主語を省略しても通じる文章が、英語では通じないなど。

英訳して日本語をチェックする私のおスメの方法は下記です。

英訳 -> 日本語訳を繰り返してみて、おかしな日本語になってしまったら修正ポイントです。

以上です。レビューは自分でもある程度はできるので、ドキュメントやブログを書いた後の見返しの癖をつけてみてください。
最後に参考の利用を紹介して終わりにします。

ドキュメントサイトの作成に困っていたり、テクニカルライターを探している方は、ぜひtwitterにDMください。何かお力になれるかもしれません。

読んでいただきありがとうございます。