textlint-rule-preset-ja-technical-writing

textlint-rule-preset-ja-technical-writing

技術文書向けのtextlintルールプリセットです。 全体的に少し厳しめの設定がデフォルト値となっているため、文章に合わせて設定値を変更する必要があります。

また、連続できる最大の漢字長は6文字まで のように文章全体として例外が必ず出てくるルールもデフォルトで入っています。 ルールによってはallowオプションで例外を規定できるようになっているため、例外を明示しつつ利用することを想定しています。

合わせて利用することを想定しているfilterルール(例外を明示できる)も参照してください。

• textlint/textlint-filter-rule-comments
• textlint/textlint-filter-rule-allowlist

Install

npmコマンドを使ってインストールできます。

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

安定版は、半年(1月と7月)に一度更新されます。

次のように@nextをつけることで、次期バージョンをインストールして試せます。 安定版と次期バージョンの差分はVersion PackagesのPRで確認できます。

npm install textlint-rule-preset-ja-technical-writing@next

もし、次期バージョンを利用してみて問題があった場合は、コメントでお知らせください。

Usage

Via .textlintrc.json(Recommended)

{
  "rules": {
    "preset-ja-technical-writing": true
  }
}

Via CLI

textlint --preset ja-technical-writing README.md

ルールの設定方法

次のように "preset-ja-technical-writing" 以下にそれぞれのオプション値を指定することで、設定を変更できます。 各ルールの設定できるオプションは、各ルールのREADMEを参照してください。

{
  "rules": {
    "preset-ja-technical-writing": {
      "max": 120,
      "no-mix-dearu-desumasu": false
    }
  }
}

また、ルールの設定方法についてはtextlintのドキュメントも参照してください。

ルール一覧

• 1文の長さは100文字以下とする
• カンマは1文中に3つまで
• 読点は1文中に3つまで
• 連続できる最大の漢字長は6文字まで
• 漢数字と算用数字を使い分けます
• 「ですます調」、「である調」を統一します
• 文末の句点記号として「。」を使います
• 二重否定は使用しない
• ら抜き言葉を使用しない
• 逆接の接続助詞「が」を連続して使用しない
• 同じ接続詞を連続して使用しない
• 同じ助詞を連続して使用しない
• UTF8-MAC 濁点を使用しない
• 不必要な制御文字を使用しない
• 不必要なゼロ幅スペースを使用しない
• 感嘆符!！、疑問符?？を使用しない
• 半角カナを使用しない
• 弱い日本語表現の利用を使用しない
• 同一の単語を間違えて連続しているのをチェックする
• よくある日本語の誤用をチェックする
• 冗長な表現をチェックする
• 入力ミスで発生する不自然なアルファベットをチェックする
• 対になっていない括弧をチェックする

1文の長さは100文字以下とする

https://github.com/textlint-rule/textlint-rule-sentence-length

長過ぎる文は読みにくさに繋がるため、適切な長さで文を句点（。）などで区切ってください。 厳しめの設定にしたい場合は90文字を推奨しています。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "sentence-length": {
        "max": 100
      }
    }
  }
}

過去の設定の履歴は以下のようになっています。

• バージョン3.0.0+: 100文字以下
• バージョン2.0.0以下: 90文字以下

カンマは1文中に3つまで

https://github.com/textlint-rule/textlint-rule-max-comma

カンマ（,）の多用は、文が長くなっている可能性があります。 1文が長くなると読みにくなっている可能性があるため適切な長さで文を句点（。）などで区切ってください。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "max-comma": {
        "max": 3
      }
    }
  }
}

読点は1文中に3つまで

https://github.com/textlint-ja/textlint-rule-max-ten

読点（、）の多用は、1文が長くなっている可能性があります。 1文が長くなると読みにくなっている可能性があるため、適切な長さで文を句点（。）などで区切ってください。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "max-ten": {
        "max": 3
      }
    }
  }
}

連続できる最大の漢字長は6文字まで

https://github.com/textlint-ja/textlint-rule-max-kanji-continuous-len

漢字同士が連続していると読みにくさにつながります。 デフォルトでは連続する漢字は、6文字までとしています。

6文字以上の固有名詞は allow オプションに記述して回避できます。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "max-kanji-continuous-len": {
        "max": 6,
        "allow": []
      }
    }
  }
}

漢数字と算用数字を使い分けます

https://github.com/textlint-ja/textlint-rule-preset-JTF-style

数量を表現し、数を数えられるものは算用数字を使用します。任意の数に置き換えても通用する語句がこれに該当します。

慣用的表現、熟語、概数、固有名詞、副詞など、漢数字を使用することが一般的な語句では漢数字を使います。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "arabic-kanji-numbers": true
    }
  }
}

「ですます調」、「である調」を統一します

https://github.com/textlint-ja/textlint-rule-no-mix-dearu-desumasu

文章の「ですます調」、「である調」を統一してください。 文体は見出し、本文、箇条書きの中で、それぞれ統一した表記にします。

デフォルト設定は次の通りです。

• 見出しは自動
• 本文はですます調
• 箇条書きはである調

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-mix-dearu-desumasu": {
        "preferInHeader": "",
        "preferInBody": "ですます",
        "preferInList": "である",
        "strict": false
      }
    }
  }
}

文末の句点記号として「。」を使います

https://github.com/textlint-ja/textlint-rule-ja-no-mixed-period

文末には「。」を使い文を区切ります。

「。」のつけ忘れのチェックや「:」で文を終わらせないようにします。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "ja-no-mixed-period": {
        "periodMark": "。"
      }
    }
  }
}

二重否定は使用しない

https://github.com/textlint-ja/textlint-rule-no-double-negative-ja

二重否定は文章を読みにくくするため、使用しないようにします。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-double-negative-ja": true
    }
  }
}

ら抜き言葉を使用しない

https://github.com/textlint-ja/textlint-rule-no-dropping-the-ra

ら抜き言葉は話し言葉のため、書き言葉である文章では使用しないようにします。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-dropping-the-ra": true
    }
  }
}

逆接の接続助詞「が」を連続して使用しない

https://github.com/textlint-ja/textlint-rule-no-doubled-conjunctive-particle-ga

逆接の接続助詞「が」は、特に否定の意味ではなくても安易に使われてしまいがちです。

同一文中に「が」が複数回出現していないかをチェックします。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-doubled-conjunctive-particle-ga": true
    }
  }
}

同じ接続詞を連続して使用しない

https://github.com/textlint-ja/textlint-rule-no-doubled-conjunction

「しかし、〜。しかし、〜」のように同じ接続詞が連続すると、文章が読みにくくなります。 同じ接続詞が連続して使用されていないかをチェックします。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-doubled-conjunction": true
    }
  }
}

同じ助詞を連続して使用しない

https://github.com/textlint-ja/textlint-rule-no-doubled-joshi

文中で同じ助詞が連続すると文章が読みにくくなります。 1つの文中に同じ助詞が連続して出てくるのをチェックします。

修正方法としては、次のようなものがあります。

• 助詞の書き間違いなので、別の助詞に置き換える
  • 例) 私は彼は好きだ → 私は彼が好きだ
• 複数のことを1つの文で書いている可能性があるため、助詞が連続している文を分割する
  • 1文でまとめようとして、無理やり助詞で文を繋いでいる可能性があります
  • 文自体を分けることで、同じ助詞が連続していることがなくなります
  • 例) https://github.com/asciidwango/js-primer/pull/1598#discussion_r1110939474
• 助詞で無理やり文を繋げている可能性があるので、文の中で順番を入れ替える
  • 助詞で文の中身を無理やり繋げようとしていて、使える助詞の選択肢が狭くなっている可能性があります
  • 文の流れを箇条書きなどにして整理してみてください
  • 例) https://github.com/asciidwango/js-primer/pull/1594#discussion_r1110973573
• 助詞が不要なら削除して、文を簡潔にする
  • "実際に" などのように強調的な言葉を削除することで、助詞が不要になる可能性があります
  • 技術文書では簡潔な文章を心がけることが多いため、強調的な単語自体を削除することもあります

例外も多いため、詳しくはtextlint-rule-no-doubled-joshiのREADMEを参照してください。 また、allowオプションで、特定の助詞が連続して出てくることを許可できます。

文自体を直す余地がない場合は、コメントなどを使ってエラーを無視してください。

• Ignoring Text · textlint

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-doubled-joshi": {
        "min_interval": 1
      }
    }
  }
}

UTF8-MAC 濁点を使用しない

https://github.com/textlint-ja/textlint-rule-no-nfd

文章中にUTF8-MAC 濁点は使用しないようにします。 ファイルからコピー＆ペーストした文字である場合があります。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-nfd": true
    }
  }
}

不必要な制御文字を使用しない

https://github.com/textlint-rule/textlint-rule-no-invalid-control-character

改行(\n)やタブ(\t)以外の制御文字が文章に入るのを防止します。

不必要な制御文字は文字化けの原因となるため、使用しないようにします。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-invalid-control-character": true
    }
  }
}

不必要なゼロ幅スペースを使用しない

https://github.com/textlint-rule/textlint-rule-no-zero-width-spaces

ゼロ幅スペース（\u200b）が文章に入るのを防止します。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-zero-width-spaces": true
    }
  }
}

感嘆符!！、疑問符?？を使用しない

https://github.com/textlint-rule/textlint-rule-no-exclamation-question-mark

技術文書では、感嘆符（!！）、疑問符（?？）は基本的には使用しないでください。 特定の感嘆符や疑問符を使用する場合は、オプションで許可するか、コメントなどで例外として無視してください。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-exclamation-question-mark": true
    }
  }
}

半角カナを使用しない

https://github.com/textlint-ja/textlint-rule-no-hankaku-kana

全角カタカナを使用してください。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-hankaku-kana": true
    }
  }
}

弱い日本語表現の利用を使用しない

https://github.com/textlint-ja/textlint-rule-ja-no-weak-phrase

〜かもしれない や 〜と思います 等の弱い表現を使用しないでください。 技術文書で曖昧な表現を避けるようにするためのルールです。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "ja-no-weak-phrase": true
    }
  }
}

同一の単語を間違えて連続しているのをチェックする

https://github.com/textlint-ja/textlint-rule-ja-no-successive-word

同一の単語(形態素解析したtoken)が連続している場合は、入力ミスや誤字の可能性があります。

誤字でない場合は、Issue報告してください。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "ja-no-successive-word": true
    }
  }
}

よくある日本語の誤用をチェックする

https://github.com/textlint-ja/textlint-rule-ja-no-abusage

日本語や技術表現における漢字の誤用などをチェックするルールです。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "ja-no-abusage": true
    }
  }
}

冗長な表現をチェックする

https://github.com/textlint-ja/textlint-rule-ja-no-redundant-expression

冗長な表現とは、その文から省いても意味が通じるような表現を示しています。 "することができる"という冗長な表現を"できる"にするといったルールです。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "ja-no-redundant-expression": true
    }
  }
}

入力ミスで発生する不自然なアルファベットをチェックする

https://github.com/textlint-ja/textlint-rule-ja-unnatural-alphabet

リイr−ス などIMEの入力ミスが日本語中に混じった不自然なアルファベットをチェックします。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "ja-unnatural-alphabet": true
    }
  }
}

対になっていない括弧をチェックする

https://github.com/textlint-rule/textlint-rule-no-unmatched-pair

1文中で対になっていない括弧チェックします。 (に対応する)がない場合や、[に対応する]がない場合などをチェックします。

デフォルト設定は次の通りです。

{
  "rules": {
    "preset-ja-technical-writing": {
      "no-unmatched-pair": true
    }
  }
}

Changelog

See Releases page.

Semantic Versioning Policy

次のルールでバージョンが更新されます。

• Patch リリース
  • 各ルールのバグ修正 (警告を減らす方向への修正)
  • ドキュメントの改善
  • 内部的な変更 (リファクタリングやテストの改善など)
  • リリース失敗時の再リリース
• Minor リリース
  • 各ルールのバグ修正 (警告を増やす方向への修正)
  • 新オプションの追加
  • 既存ルールの非推奨化
• Major リリース
  • プリセットへのルールの追加
  • プリセットからルールの削除
  • 既存のオプション値の変更

更新内容はReleases pageを参照してください。

Release Flow

• 次のMajorバージョンのIssueを作り、IssueにCHANGELOGを書いていく
• Pull Requestはrenovatebotから出るのでマージする
• 半年ごとにリリース用のIssueが作られるので、確認してリリース用のPRをマージする
• リリースされたらIssueをクローズする

ルールの利用者

このプリセットを利用しているユーザーです。

• asciidwango/js-primer
• Maven3のはじめかた

ユーザーリストへのPRも募集しています。

Community

質問は以下のGitterでお願いします。

その他のルール

• Collection of textlint rule · textlint/textlint Wiki

Running tests

npm test

Contributing

Pull requests and stars are always welcome.

For bugs and feature requests, please create an issue.

• Fork it
• Create your feature branch: git checkout -b my-new-feature
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request :D

Author

• github/azu
• twitter/azu_re

License

MIT © azu

Changelog

12.0.2

Patch Changes

• dba9f59: CI: prevent snapshot release from branch