textlintとreviewdogを導入してREADMEや技術文書の質を向上させよう

開発チームの一員として加わっていると、ドキュメントを書く機会は非常に多くなります。
GithubリポジトリのREADMEやConfluence、Backlogなどに技術文書を残すタスクは必ず訪れます。新しく参加するエンジニアへのオンボーディングや、協業して実装する仲間に対して、良質な文書を残せるスキルはエンジニアに必須となりました。

そういったドキュメント作成タスクにおいて、とても便利なtextlintとreviewdogについて紹介していきます。
非エンジニアだと導入に手こずるかもしれませんが、チーム内全員で使いたいほど素晴らしいソフトウェアです。

エンジニアのドキュメント作成にtextlintとreviewdog

textlintとreviewdogは導入にあまり手間がかからないので、ぜひさくっとインストールして手元で試してみてください。
なお、書き溜めたドキュメントを一括で検査すると絶望する量のエラーが返ってくるので、今まで書いたものに適用することはおすすめしません。（すごく大変でした）

まずは各ソフトウェアの概要から説明します。

textlintとは

text（テキスト）のlinter（解析ツール）です。ドキュメントを解析した上で、どこが冗長か、二重表現はあるかなどを提示してくれます。

例として、以下の文書をtextlintのpreset-ja-technical-writingプラグイン（技術文書用プラグイン）で解析した結果を見てみましょう。

今日はtextlintについて紹介したいと思います！
文章の作成を行う上で、textlintは効率的で革新的で素晴らしいものです。
あなたのドキュメント作成能力を向上できるかもしれないので導入していませんか？

textlint test.txt

こちらの結果は以下となります。
「思います」や「かも」といった弱い表現、「！」「？」のような技術文書にふさわしくない表現がエラーとして出力されます。

reviewdogとは

reviewdogはGithubなどのコードホスティングサービスに対して、コメントを自動で付与できるソフトウェアです。
コードレビューの自動化で役立つため、対応している言語のプロジェクトで利用すると捗ります。

先ほどのテキストを含むデータをGithubでPullRequestした結果は以下です。
textlintで出力した結果と同じものがコメントとして投稿されます。

この結果はPullRequestのコメントに出力していますが、reporterと呼ばれる出力先を指定できます。

reviewdogとCI/CDの組み合わせ

reviewdogはその特性上、CI/CDと組み合わせて利用します。
以下が2023年8月現在、サポートされているCI/CDプロダクトです。

• Github Actions
• Travis CI
• Circle CI
• GitLab CI
• Bitbucket Pipelines

GitOpsやDevOpsと呼ばれる開発・運用サイクルに差し込むだけで、高品質なプロダクトを保持できます。今回のtextlintだけでなく、linterを取り入れているプロジェクトには積極的に活用していきましょう。

textlint + reviewdog構築例

今回はいくつかの便利プラグインと共に、簡単な導入手順を説明します。

textlintの設定例

textlintはローカルの確認でも使えるため、手元のパソコンにインストールしておきましょう。ただし、globalインストールした状態で使い続けると、この後のreviewdogでドはまりします。（実際にハマりました）
なので、今回は適当なプロジェクトを作って開始します。

mkdir -p ~/workspace/reviewdog-sample/doc

cd ~/workspace/reviewdog-sample

npm install textlint textlint-filter-rule-comments textlint-rule-preset-ja-technical-writing

ここでインストールしているtextlintのプラグインは以下です。

• textlint-filter-rule-comments: 特定条件でlintを無視できる
• textlint-rule-preset-ja-technical-writing: 日本語技術文書用ルール

次に、テスト用のテキストファイルをdoc/以下に作りましょう。内容はなんでも良いですが、今回は先に紹介したテキストファイルを流用します。

今日はtextlintについて紹介したいと思います！
文章の作成を行う上で、textlintは効率的で革新的で素晴らしいものです。
あなたのドキュメント作成能力を向上できるかもしれないので導入していませんか？

textlintは、.textlintrcファイル、あるいは.textlintrc.jsonを設定ファイルとして認識します。
今回は.textlintrc.jsonを作りましょう。

{
  "filters": {
    "comments": true
  },
  "rules": {
    "preset-ja-technical-writing": true
  }
}

そして、以下のコマンドを実行します。

textlint --config .textlintrc.json doc/test.txt

エラーを出力すればOKです。
これでtextlintは導入完了です。

reviewdog + Github Actionsで動かす

textlint + reviewdogをGithub Actionsへ適用するのに便利なActionをTsuyoshi CHO氏が開発してくれています。今回はそれを利用しましょう。

これを利用するためのGithub Actionsワークフローを設定します。

mkdir -p .github/workflows

vi .github/workflows/reviewdog.yml

以下はaction-textlintのREADMEに掲載されているサンプルからnodeのバージョン周りを少し改変しています。（ローカルに合わせるため）

name: reviewdog
on: [pull_request]
jobs:
  textlint:
    name: runner / textlint
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          submodules: true
      - name: Setup node/npm
        uses: actions/setup-node@v3
        with:
          node-version: 16
      - name: textlint-github-pr-check
        uses: tsuyoshicho/action-textlint@v3
        with:
          github_token: ${{ secrets.github_token }}
          reporter: github-pr-check
          textlint_flags: "doc/**"
      - name: textlint-github-check
        uses: tsuyoshicho/action-textlint@v3
        with:
          github_token: ${{ secrets.github_token }}
          reporter: github-check
          textlint_flags: "doc/**"
      - name: textlint-github-pr-review
        uses: tsuyoshicho/action-textlint@v3
        with:
          github_token: ${{ secrets.github_token }}
          reporter: github-pr-review
          textlint_flags: "doc/**"

ここまで完了したらpushしてPullRequestを出してみましょう。
Github Actionsが動き始めます。

先に紹介したように、ここでコメントにtextlintの結果が登場したら成功です。

技術系ドキュメントの冗長性を減らそう

READMEや技術系の記事を書く際、詳細に書こうと力を入れると冗長になりすぎることがあります。書き込む、という気持ち自体は良い姿勢ではありますが、我々エンジニアにとって冗長性は可能な限り省きたいものです。
コードと違って、文章はベストプラクティスが一定ではない問題をtextlint + reviewdogで解決していければ最高です。

文章だけでなく、reviewdogでlinterを走らせればコードレビューの時間短縮にもなります。ぜひガンガン活用していきましょう。