はじめに
こんにちは、ホワイトプラスのコアシステム開発グループでエンジニアリングマネジャー（EM）をしているinouehiです。
私はエンジニアの仕事の中で重要な位置を占めるコミュニケーションに興味を持っています。今回はその中でも、ドキュメントによるコミュニケーション、特に文章に注目したいと思います。
よいドキュメントと悪いドキュメント
ドキュメントとは、誰かの頭の中にある暗黙知を見える化して他者への共有を可能にする仕組みと私は捉えています。これにより、ナレッジの拡散をある程度自動化したり、業務の属人化を軽減する等の効果が期待できます。うまく作られたドキュメントからは、かける手間に対して大きな恩恵を得られると考えています。
その一方、陳腐化したドキュメントが誤った情報を拡散するという側面もあるので、ドキュメントを作ってお終いではなくメンテナンスとセットと考えています。メンテナンスコストを高く見積もりドキュメントを作らないという考え方があることも理解しつつ、再利用性の高いナレッジを選ぶ等、労力対効果の高いところをドキュメント化すべしという立場を私はとっています。また、読みにくいドキュメントがミスリードしたり人の時間を奪う側面もあるので、読み手にやさしい読みやすいドキュメントを書くべしとも思っています。リーダブルなコードを書きましょうというのと同じ気持ちです。
読みやすい文章とは
本稿ではドキュメントの構成要素の中でも文章に注目したいと思います。私が文章を書く際に、2つの視点で気をつけていることがあります。1つは、構成。もう1つは、文そのものです。
構成に関しては、例えば以下のようなことを心がけています。
- 目的を明確にする。
- 書きたいことを箇条書きにしてから書き始める。
- 想定する読者を明確にする。
- 読者に差し上げる価値を考える。
- 構成を考える。情報を並べる順序に気を配る。
- 認知負荷を減らせるような順にする。
- 見直して、順序を入れ替えたり表現を見直す。
文に関しては、例えば以下のようなことを心がけています。
- 一文を短く切る。
- 多義性を抑える。
- 修飾語と被修飾語を近づける。
- 修飾を不用意に連発しない。
- 指示語が指すものを明確にする。
- 意味が限定できる語順を選ぶ。
- 句読点を打つ。
- 省略しない。
- 接続詞を使い、文章の論理関係を明示する。
- （ドキュメントの目的次第で）無くても文意に影響を与えない言葉を省く。
細かく言えばもっと多くのルールを自分に課しています。しかし、これだけに絞ったとしても自分が全て実践できている自信もなければ、読みやすい文章を書けている自信もありません。文章を書くということは、様々なことを同時に考えなければならない認知負荷の高い行為だと私は考えています。これを人の力だけでパーフェクトにやりきるのは至難の業です。そこで機械の力をかりたいと思います。プログラムを静的解析でチェックするのと同様に、自然言語をtextlintにチェックしてもらいます。
textlintはルールに従い文章を校閲してくれる仕組みです。例えば、以下のようなルールがあります。
- 一文に利用できる
、の数をチェックするルール - 「ですます」調と「である」調の混在をチェックするルール
- 二重否定をチェックするルール
- 半角カタカナの使用を禁止するルール
- "〜かもしれない" のような弱い表現の利用を禁止するルール
- 冗長な表現を禁止するルール
- よくある日本語の誤用をチェックするルール
textlintによる校閲
さて、ドキュメントの話からはやや脱線しますが、私のロールはEMでして、メンバーの評価やフィードバックを行う責務を負っています。成果やのびしろ等をフィードバックするのですが、フィードバックも文章によるコミュニケーションです。まずは内容こそが重要ではありますが、それを受け取ってもらうには伝え方も重要と私は考えます。受け取り手にストレスを与えない、理解しやすい文章にしたいのです。そこで今回は一般的な文書で利用するための日本語用のルール集を使ってチェックしてみました。
結果、以下のようなお叱りを受けました。
- Line 17 sentence length(155) exceeds the maximum sentence length of 100. Over 55 characters.
- 一つの文で"、"を4つ以上使用しています
- 一文に二回以上利用されている助詞 "に" がみつかりました。
- 一文に二回以上利用されている助詞 "が" がみつかりました。
- 一文に二回以上利用されている助詞 "か" がみつかりました。
ざっくりまとめると冗長な文章を書きがちということのように見えなくもないですがきっと気のせいでしょう。セルフチェックする前にtextlintにかけたため指摘を受けましたが、セルフチェックしていれば全部自力で直せていたはずです（言い訳）。
これを受けて箇条書きにする等の修正を行いました。自分の癖は自分では分かりにくいものですので、気づかせてもらえてありがたい限りです。
ちなみに、本稿のここまでの文章をチェックしてみたところ
セルフチェックする前にtextlintにかけたため指摘を受けましたが
の部分に対して 一文に二回以上利用されている助詞 "に" がみつかりました。 との指摘を受けました。無駄な言い訳をしようとしたがためにバチが当たりました。とはいえ、そこまでイレギュラーな文でもないと個人的には感じており、チェックが厳しいと言えば厳しいかもしれません。修正案としては「セルフチェックする前にtextlintを実行したため指摘を受けましたが」等が考えられそうです。個人的には読みやすくなった気がします。フィードバックは素直に受け取り咀嚼するのが大事ですね。どうしても納得がいかなければ、textlintにはエラーを無視する方法も用意されています。
ざっくりまとめると冗長な文章を書きがちということのように見えなくもないですがきっと気のせいでしょう。
の部分に対しては 二重否定: 〜なくもない との指摘を受けました。ブログの中の砕けた部分という文脈を踏まえ、無視することにします。
まとめ
開発をスケールしたり、息の長いサービスを保守し続けるためにドキュメントが有効であるとの立場から、特に文章の書き方、校閲の工夫についてまとめてみました。
機械と仲良くして仕事の精度を高めたり、仕事をより快適にしたいものです。
さいごに
ホワイトプラスでは、ビジョンやバリューに共感していただけるエンジニアを募集しています！
ネットクリーニングの「リネット」など「生活領域×テクノロジー」で事業を展開している会社です。どんな会社か気になった方はオウンドメディア「ホワプラSTYLE」をぜひご覧ください。
オンラインでカジュアル面談もできますので、ぜひお気軽にお問い合わせください。
