ブログ校正の作法：textlintで強化するテクニカルライティング

HRBrain Advent Calendar 2023 1日目の記事です。

はじめに

こんにちは。@yug1224(Yuji Yamaguchi)です。

今年もAdvent Calendarが始まりましたね！そろそろ記事を書かなきゃと焦っている人も多いのではないでしょうかｗ

本記事では、私が文章作成時に気を付けているテクニカルライティングの観点と、そのために使っているtextlintのルールを紹介します。

テクニカルライティングとは

テクニカルライティングとは、技術的な内容を正確かつ効率的に伝えるために誕生した文章作成技術です。

コンピューターやICT技術の発達により、今ではあらゆる職種の人に文章を書く機会があるため、テクニカルライティングの技術はビジネスパーソンにとって必須の技術となっています。

オススメ書籍

テクニカルライティングに関する書籍や記事はたくさんありますが、私は以下の書籍をよく参考にしています。

• 日本語スタイルガイド(第3版) | Amazon
• 技術者のためのテクニカルライティング入門講座 | Amazon
• エンジニアのための文章術 | Amazon
• エンジニアのためのドキュメントライティング | Amazon

とくに、日本語スタイルガイドは、3級テクニカルライティング試験[TW]のガイドブックとなっているため、テクニカルライティングを学ぶ上では必須の一冊ですね。

さらに、実⽤⽂・SNS・メールなど多様な⽂章にも対応した改訂第4版がそろそろ発行されるらしいので、そちらも楽しみです！

公用文作成の考え方

正しい日本語文章を作成するという観点では、文化庁が公開している「公用文作成の考え方（建議）」も参考になります。

• 「公用文作成の考え方」について（建議） | 文化庁
• 公用文作成の要領 | 文化庁
• 文化審議会建議「公用文作成の考え方」について | 文化庁

テクニカルライティングを学ぶと、あらゆる文章を書くときに役立ちますが、これらの観点をすべて覚えた上で文章を書くのは難しいですね。

そこで私は、文章作成時にtextlintを使い、テクニカルライティングの観点を自動的にチェックするようにしました。

textlintとは

textlintとは、自然言語用の静的解析ツールです。ルールを設定することで、文章構造や表記誤りをチェックできるようになります。

textlintには、すでに多くのルールプリセットが用意されているため、それらのルールを組み合わせることで、自分に合った校正環境をすぐに構築できます。

オススメルールプリセット

以下が、私がよく使うルールプリセットです。この他にも多くのルールプリセットが公開されているので、自分に合ったものを探してみてください。

• textlint-ja/textlint-rule-preset-ja-technical-writing
  • 技術文書向けのルールプリセット。
  • 全体的に少し厳しめ設定だが、基本的にはこれだけで十分。
• textlint-ja/textlint-rule-preset-JTF-style
  • JTF日本語標準スタイルガイドに合わせたルールプリセット。
  • 厳しすぎるルールが一部あるので、必要に応じて無効化する。
• ics-creative/textlint-rule-preset-icsmedia
  • ics.mediaで使われているルールプリセット。
  • 主にWeb記事向けのルールが含まれている。
  • 用語辞書が充実しているので、表記揺れの防止にとても有効。

textlintのルールを組み合わせる

上記のプリセットを組み合わせて、私は以下のような.textlintrcで文章校正をしています。

.textlintrc

{
  "filters": {
    "comments": true
  },
  "rules": {
    "preset-ja-technical-writing": {
      "ja-unnatural-alphabet": {
        "allow": [
          "a",
          "i",
          "u",
          "e",
          "o",
          "n",
          "/[A-Z]/",
          "/[WwＷｗ]+/$"
        ],
        "allowCommonCase": true
      },
      "ja-no-mixed-period": {
        "allowEmojiAtEnd": true,
        "allowPeriodMarks": [
          "…",
          ".",
          "。",
          "w",
          "ｗ",
          "W",
          "Ｗ"
        ]
      },
      "ja-no-successive-word": {
        "allow": [
          "・",
          "！",
          "!",
          "？",
          "?",
          "…",
          "○",
          "◯",
          "w",
          "ｗ",
          "W",
          "Ｗ"
        ]
      },
      "no-doubled-joshi": {
        "allow": [
          "も",
          "や"
        ]
      },
      "no-exclamation-question-mark": false,
      "sentence-length": {
        "max": 150
      }
    },
    "preset-jtf-style": {
      "1.1.3.箇条書き": false,
      "2.2.1.ひらがなと漢字の使い分け": true
    },
    "prh": {
      "rulePaths": [
        "node_modules/textlint-rule-preset-icsmedia/dict/prh.yml"
      ]
    }
  }
}

textlint-rule-preset-ja-technical-writing

• ja-unnatural-alphabet
  • textlint-ja/textlint-rule-ja-unnatural-alphabet
  • 不自然なアルファベットをチェックする。
  • デフォルト設定に"/[WwＷｗ]+/$"を追加することで、文末の草を許可していますｗ
• no-mixed-period
  • textlint-ja/textlint-rule-ja-no-mixed-period
  • 文末の句点の統一と抜けをチェックする。
  • "allowEmojiAtEnd": trueによって、絵文字で終わる文を許可しています。
  • "allowPeriodMarks": ["…",".","。","w", "ｗ", "W", "Ｗ"]によって、特定文字で終わる文を許可しています。
• no-successive-word
  • textlint-ja/textlint-rule-ja-no-successive-word
  • 同一の単語が間違えて連続しているのをチェックする。
  • "allow": ["・", "！", "!", "？", "?", "…", "○", "◯", "w", "ｗ", "W", "Ｗ"]によって、特定文字の連続を許可しています。
• no-doubled-joshi
  • textlint-ja/textlint-rule-no-doubled-joshi
  • 1つの文中に同じ助詞が連続して出てくるのをチェックする。
  • "allow": ["も", "や"]によって、複数回の出現を許可しています。
• no-exclamation-question-mark
  • textlint-rule/textlint-rule-no-exclamation-question-mark
  • 感嘆符と疑問符を禁止するルール。
  • ブログでは、感嘆符や疑問符を使うこともあるので、falseで無効化しています！
• sentence-length
  • textlint-rule/textlint-rule-sentence-length
  • 文の長さをチェックする。
  • 長すぎる文は読みにくいので、"max": 150に設定しています。

textlint-rule-preset-JTF-style

• 1.1.3.箇条書き
  • 1.1.3.js
  • 箇条書きの文体が、本文と一貫しているかチェックする。
  • 本文と文体が合わない場合もあるので、falseで無効化しています。
• 2.2.1.ひらがなと漢字の使い分け
  • 2.2.1.js
  • 漢字とひらがなの使い分けをチェックする。
  • 日本語スタイルガイドに合わせてほしいので、trueで有効化しています。

textlint-rule-prh

• rulePaths
  • ics-creative/textlint-rule-preset-icsmedia
  • ics.mediaで使われているルールプリセットから、用語辞書だけを利用しています。
  • GitHub VS Codeなど、表記揺れを起こしやすい技術用語を含む文章を書くときに役立ちます。

まとめ

ブログ執筆時に気を付けているテクニカルライティングの観点と、文章校正をするためのtextlintのルールを紹介しました！

ブログを書いたりレビューをする際には、実際に上記のルールを使っていますが、あまりルールに従い過ぎると、筆者の個性が失われてしまうような感覚もあります。

なので、少し厳しめのルールでチェックを行い、前後の文脈を考慮しながら塩梅を調整しています。なかなか難しいですが、そこが校正の面白さでもあるかなと思います。

ぜひ皆さんも、自分自身に合った校正環境を構築して、テクニカルライティングを楽しんでください！

PR

HRBrain Advent Calendar 2022では全61記事を投稿しましたが、HRBrain Advent Calendar 2023でも多くの記事が投稿される予定です！お楽しみに！🎉

また、HRBrainでは一緒に働く仲間を募集しています。歴史に残るトライをしよう！