長いあいだ私は技術文書を書くのは得意ではありませんでした。しかし大学院時代に論文を何度も校正していただいたことで、考えを書いて伝えるという行為についての興味が出てきました。このあたりについては過去スライドにまとめました。

RedPen

スライドにまとめた内容の一部でも自動で検知できないかと考えて、RedPenという自然言語で記述された文書を自動でチェックするツールを作っています。このツールは私が大学院時代に数多く注意を受けた部分を自動で発見したいというモチベーションではじめています。 RedPenのドキュメントはこちらを参照してください。

各機能がどういった意図で作られているのかについては文書執筆の指南書で解説されている問題点を RedPen で発見するを参照してください。 また、一旦初めてみるというときには RedPen おすすめ設定が役に立つかもしれません。

この記事をみると文の長さについての設定が初めに追加されています。理由は私が大学院時代に最も注意を受けた箇所だからです。私もそうでしたが書き慣れていないと文を短文に切断するのが怖くなります。 そのため初学者は文を長くしてしまい可読性を損ないがちです。「RedPenの言う通り短文にしたけど文章がつながらない」という状態で苦しんでいる 場合には 文が長すぎる問題とその対処が役に立つかもしれません。この記事は副詞や接続詞を使わず文をつなげる方法について解説しています。

RedPenについてはいくつか記事を書いています。RedPenを使って技術文書を手軽に校正しようはRedPenについて初めて書いた記事です。内容は古いですが、 Continuous Integrationで使う方法やその他内部の表現などが記述されています。ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]は実際に マークアップ言語を使って記事を書くときに役立つことをまとめた資料です。実際にRedPenを使って記述した論文のレポジトリに拡張可能なドキュメント検査ツール RedPenがあります。 内容はRedPenの紹介に過ぎませんが、MakefileやRedPenの設定などは役に立つかもしれません。

スライド

ミートアップなどで使用するスライドを校正する方法について過去にまとめた記事です。これも大学院時代に指摘していただいたところをまとめた内容となっています。