だいくしー(@daiksy)のはてなブログ

daiksyの徒然的なもの 以前のブログはこっち -> http://daiksy.blogspot.jp/

技術文書の執筆にめちゃくちゃ便利なtextlint

現在、少し長い技術文書を執筆する機会があって、ここ半月ほど毎週末にまとまった文章を書いている。

ここまで長い文書をまとめて書くのは、大学の卒業論文以来かもしれない。

書くにあたって、だいたいのエンジニアがそうするであろう振る舞いとして、『理科系の作文技術』を再読した。

あとは校正の手間をできるだけ省くために、リアルタイムでおかしい文章に気づけるようにtextlintを使ってみた。これも初体験。

github.com

特に、日本語の技術文書を添削してくれる textlint-rule-preset-ja-technical-writing が死ぬほど便利だ。

github.com

デフォルト設定からちょっとだけアレンジした。

{
  "filters": {},
  "rules": {
    "preset-ja-spacing": true,
    "preset-ja-technical-writing": {
      "max-ten": {
          max: 4
      },
      "ja-no-mixed-period":false
    },
    "spellcheck-tech-word": true
  }
}

max-ten は一文中の読点の数が設定を超えたら怒ってくれる。デフォルト値は3だが、ちょっと制限がきつすぎるなと感じたので4にした。

ja-no-mixed-period は句点が無いと怒ってくれるのだが、見出しのように句点を打ちたくない箇所で大量に怒られるので、これはfalseにした。

ぼくがよく怒られるのは次の2つ。

「助詞の連続使用」とくに"が"、"に" あたりでしょっちゅう怒られる。

「〜だと思います」と書いてしまう。技術文書は主張をはっきりさせるべきなので、曖昧な表現は使うべきではない。ぼくはしょっちゅ「かもしれない」「思います」と書いて怒られる。怒られまくる。ぼくが普段いか に曖昧な文章を書いているのかということをつきつけられる毎日である。

あと、意味の重複する言葉もけっこう怒られる。「することができる」は「できる」と書け、とよく言われる。

これらは気をつけていても油断すると書いてしまうので、書いた瞬間に怒ってくれるtextlint最高である。

ちなみにこのblogは原稿を書かねばならない現実逃避によって書かれている。この分量を本来書くべき原稿に書いていたら進捗を得られていたのだが...。