開発ドキュメントの文章を自動で校正する方法【textlint】
私はテクニカルライターとして、開発ドキュメントを書いています。開発ドキュメントを書く上で、文章をよりよくするには、「校正」というプロセスが必要になります。
この校正というのは、誤字・脱字を直したり、文章全体を読みやすくしたりする、という作業になります。
この校正は、もちろん目視でやることもできますが、自動で行うこともできます。この記事では、校正とは何か、そしてこの校正を自動で行う方法として「textlint」というツールの説明をします。
この記事を読むことで、よりよい文章を効率的に書けるようになるきっかけになれたらと思います。
目次
校正とは何か
まず校正について整理します。校正とは、文章の誤りを正す作業になります。例えば誤字・脱字を見つけて、それを直す作業が校正です。
この校正は、元々は「原稿と製作物の文字に違いがないかを、一字ずつ確認する作業」のことを意味していました。
他にも校正には、次のような「読みやすい文章にするための修正」も含まれます。
- 一文が長すぎないか
- ら抜き言葉はないか
- 敬体・常体を混ぜていないか
このように、よりよい文章にするために必要なプロセスが校正になります。
開発ドキュメントを書くときはもちろん、ブログだったり、Twitterだったりなど、文章を書くときにこの校正という作業をすることによって、よりよい文章につながっていきます。
自動校正ツール
この校正という作業は、目視で行うことができます。私もよく目視で校正を行います。
ただ目視だけだと、どうしてもミスが発生してしまいます。人がやる以上、このミスは避けられないと思います。
ここで役に立つのが校正ツールです。校正ツールでは、誤字・脱字や、変換ミスなどを検出することができます。
例えば校正ツールには、次のようなツールがあります。
ただ、これらのツールは、フォームに文章を入力しないといけません。手間がかかりますし、サーバに文章が送られることにもなります。企業によっては、情報管理の関係上こういったツールを採用できないかもしれません。
他にも、「校正を自動で行いたい」とか、「もっと広いルールで校正をしたい」という要望があるかもしれません。それができるのが「textlint」というツールになります。
textlintとは
textlintのトップページ
textlintは文章やMarkdownのための校正ツールになります。例えばテキストエディタで文章を書くとき、ルールに従ってミスを指摘してくれます。
例えば「一文が長過ぎる」とか「ら抜き言葉がある」といったミスを自動で検出してくれます。その場で修正することによって、よい文章を効率的に書けるようになります。
このtextlintを使うことで、次のようなメリットがあります。
- さまざまなルールがある
- 日本語のルールが豊富
- ルールをまとめたプリセットがある
- エディタ向けの拡張がある
- 自動で校正してくれる
- 設定を共有できる
- 無料で利用できる
これらのメリットについて、簡単に整理します。
textlintでは、誤字・脱字だけでなく、広いルールで校正をすることができます。ルールの一覧は次のページで公開されています。ご覧の通り、日本語のルールがとても豊富です。これは作者が日本の方ということもあるかもしれません。
ルールがたくさんあってどれを選べばいいかわからない、というときは、ルールをまとめた「プリセット」というものを使うといいと思います。開発ドキュメントを書く場合は、技術文書向けのプリセットを使うといいです。これひとつ導入することで、オールインワンでルールが揃います。
またVS CodeやVimのようなエディタ向けの拡張機能もあります。この拡張機能を導入することで、エディタで文章を書いているときに、自動でミスを指摘してくれます。
textlintのルールは、ファイルとしても共有できます。Gitなどで管理すれば、チームの中で同じルールをもとに文章を書くことができます。つまり、チーム内で文章の品質を一定以上に保つことができます。
ここまでできて、textlintはOSSとして公開されています。つまり無料で利用することができます。
企業等でtextlintを導入する場合は、作者のスポンサーになることで支援することもできます。ぜひ検討してみてください。
textlintの導入方法
ここではGitで管理しているプロジェクトにtextlintを導入します。あわせて、技術文書向けのプリセットを導入します。これは次のコマンドを実行します。
$ npm install --save-dev textlint textlint-rule-preset-ja-technical-writing
これだけで、textlintの実行環境と、必要なルールが揃います。
次にtextlintの設定ファイルを準備します。.textlintrcというファイルを作成して、次のように記述します。
{
"rules": {
"preset-ja-technical-writing": true
}
}
あとは、次のコマンドで校正を実行します。校正したいファイルをfile.mdだとすると、
$ ./node_modules/.bin/textlint file.md
となります。textlintの始め方について詳しくは、公式ドキュメントの「Getting Started with textlint」をご覧ください。
基本的には、上記のようにコマンドを実行することで校正を行いますが、テキストエディタの拡張機能を入れることで、文章を入力中に自動で校正をしてくれます。
代表的な拡張機能を次に紹介します。
- VSCode: vscode-textlint
- Atom: linter-textlint
textlintのカスタマイズ方法
実際にtextlintを実行したら、指摘がたくさん入るかもしれません。書いている文章によっては、「ルールが合わない」ということが出てきます。
この場合は、文章をルールに合わせる必要はありません。textlintでは、ルールの方を細かくカスタマイズすることができます。
例えば技術文書向けのプリセットの場合、一文の長さは100文字となっています。これを120文字にするときは、次のように設定します。
{
"rules": {
"preset-ja-technical-writing": {
"max": 120
}
}
}
カスタマイズ方法について詳しくは、「Configuring textlint」をご覧ください。
CIによる自動校正
textlintは手元で実行するだけでも効果的ですが、GitHub ActionsやCircleCIなどのCI環境で設定すると、ミスを含んだ文章を公開することを防げます。
CIによる自動構成については、次の記事が参考になります。CIの設定だけでなく、textlint自体の設定についても参考になるので、ぜひご覧ください。
おわりに
よりよい文章にするには、校正という作業が必要になります。この校正を自動で行うツールとして、textlintを紹介しました。
この記事が、よりよい文章になるきっかけになればうれしいです。
