ツナワタリマイライフ

日常ネタから技術ネタ、音楽ネタまで何でも書きます。

「エンジニアのための文章術再入門講座」を読んでドキュメント作成スキルの振り返りをする

はじめに

良いドキュメントを書くことはエンジニアのたしなみ。ということで定期的に自身のドキュメントスキルの見直しを行っています。

エンジニアのための文章術再入門講座

エンジニアのための文章術再入門講座

ドキュメントといえば結城先生の数学文章作法もおすすめ。

で、この"エンジニアのための文章術再入門講座"なんですが、各章ごとにエッセンスを紹介して、そのあと具体例を用いて悪い文章を良い文章に直す、というスタイルで進んでいきます。ただ、この例がかなり自分にとってはしっくりこず、本当にこんなドキュメントわざわざ書くやつおるんかいな、と思うシーンがほとんどで、僕はエンジニアのはずなのにおかしいなぁと思ってしまいました。

とはいえ、書いてある観点そのものは正しいと思うので、その点にしぼって振り返りをしてみます。

エンジニアにとってのドキュメント

その前に、エンジニアにとってなぜドキュメントスキルが必要か、ということを再認識しておきましょう。

本書でも一章で、ドキュメントはエンジニアのスキルを表すということが言及されていますが、信頼できる文章を書くことで技術的にも期待されるという面は確かにあると思います。

私は本書の例にあるようにお客様にシステムを提案するドキュメントを書くことも、経営層に投資対象を選択してもらうためのドキュメントを書くこともありません。

今の私が仕事でドキュメントを書くシーンは

  • ツールやコードのREADME、MergeRequestでの仕様説明
  • チームメンバーや後輩への業務指示
  • チーム内で遵守すべき共通ルール
  • ナレッジ(技術的知見)の共有
  • 業務上不明点の相談、報告
  • 業務進捗報告
  • イベント参加報告

ぐらいでしょうか。どれもたいしたことないように思えますが、なるべく一発で相手に伝わるドキュメントを書くスキルは重要だと以前より考え、ブログでのアウトプットを続けているのもその一環です。(時間に余裕が無い時スピード重視で雑なままつきとばしてしまうことが最近あって、反省。。。)

チーム内でもドキュメントに対するこだわりは強いのですが、実力はまだついていないようで、まだ他者に褒められるまではいたってないので今後も精進。。。

ドキュメントを書く時の心がけ

本書第2章で語られている以下の2点は正しいと思います。

ルール① 目的にフォーカスする ルール② 相手にフォーカスする

結城先生も「読者のことを考える」だけをひたすら言い続けた本を書いたわけですが、その読者がどういう知識レベルで、どういう目的で読むかを考えることが第一に大切なことだと思います。

プレゼンのときに「対象は誰で」「知識レベルはどれぐらいで」「何を持って帰ってもらうことが目的なの」ということを考えますが、それと同じですね。

論点を絞る

本書第3章では、伝えたいことを1つがテーマです。本筋に余計なことが書かれていると気が散りますよね。

余談ですが、余談ですがで本筋を見出しまくったココイチ好きすぎな記事を昨日読んで、なるほどカレーが食べたくなっちゃうなーと思いました。余談ですが。

www.mikinote.com

本書まとめでは「論点を絞る」ことに関するチェックポイントが5つもあってなかなか絞りきれないと感じました。

論理的記述力

4章、主張をしたら根拠を述べる。

まぁ、そうねって感じですね。

ちなみにまとめで5つのチェックポイントがあるわけですが、5つめの受け身表現や稚拙表現を使わない、がカテゴライズされてるのが謎です。この主張自体は正しいのですが、論理性による文章の信頼性担保のついでに、受け身表現も信頼度減るよ、稚拙表現(これはこれでまた曖昧な表現ですが)も信頼度減るよ、だからやめようね、のついで感があります。

構造化力

5章、同じグループをまとめたり、同じ階層ではレベルを揃えるとのこと。これはとても重要ですね。

箇条書きでよくやりがちなのは、粒度が揃っていなかったり、論理展開を並べてしまったりする場合があります。

# 私とカレーについて
* カレーが好き
* キーマカレーが好き
* 週末はよくカレー作りをする

おいおいカレーとキーマカレーは粒度が違うやないかい、カレーの好みと、カレーをどう好きかもまた粒度が違うやないかいってなりますよね。

# 私とカレー
* カレーはおいしい
* カレーを作ってみようと思った
* カレーエンジニアに

まぁそんな流れでカレーエンジニア(ってなんだよ)になったのかなーってのはなんとなくわかるけど、思考の流れや論理展開を箇条書きにするのも好ましくないと思います。伝わるけどね。

平易表現力

本書第6章です。

難しい用語、専門的な用語、自分やチームの人しかわからない言葉は、言い換えて表現する ただし、文章に前修飾すると分かり難いので、脚注やカッコを使う

"一言で言う「結論」"で「ただし」と足されているところがしっくりきませんが、使う用語は読者が理解できるものしようというのは正しいと思います。

これは冒頭で述べた「読者の知識レベルを考える」でカバーできる範囲だと思います。

正確表現力

7章です。

自分が知っていることを省略しない、あくまで相手の知識や理解をベースに書く 主語や主体は明確に書く 曖昧な表現や無意味な表現をしない

3点目の曖昧な表現や無意味な表現がとってもブーメランになってる気がしますが、暗黙的な理解を省略してしまうことはあると思うので、前提が相手にはわかるかな?という視点は大切かと思います。

あとここに関連するか微妙ですが、略語を使わないということも大事ですね。(略語も省略といえばそうなので) 少なくとも1回目は正式名称で述べ、以降略するとか。ついついチーム内への提案ドキュメントにcapistranocapiと書いてしまって最近指摘されました。capiって言うもん。ごめんなさい。

A remote server automation and deployment tool written in Ruby.

capiはいいぞ。

短文表現力

8章

無駄な文章をそぎ落とす 図解や記号化を行い、文章を画像として扱う 短くするための言い換えを使う

!? って感じのまとめですが、できるだけ短くしようね、ということは納得します。

論理展開を→を使って省略するということが主張のようですが、まぁ好みの問題かなと思います。

体現止めにしてブロックにしてそれを矢印で遷移させるのはプレゼンの領域でしょう。

感情・心理利用力

相手の感情に訴えるなど、心理面のアプローチをドキュメントに埋め込む 複数案から選ばせることで、こちらの意図した方向に誘導するなどの技術を駆使する

上記の結論を添削するなら、本書はドキュメントに関する指摘をしているので"ドキュメントに"埋め込む は冗長。

意図した方向に誘導する"など" という曖昧な表現は排除すべきですね。

で、ここにきて感情論かよ、って思いそうになりますが、これは「相手の気持ちを考える」ということなので、とても良いことです。つまり提案を受ける側の選びやすい形にしてあげる、と捉えることができます。

まぁなんか相手を褒めるとかも書いてありますが、うん、まぁ、そうね、普段のコミュニケーションとしては大事です。

この章、言ってることは間違ってはいないのですが、ドキュメントの技術的な校正を考えるなら除外すべき章だと思いました。もう少し大きな枠組みで、チームで働くときに気をつけるべきメンバーへの働きかけ方、という範囲で述べられることかなと思いました。

フレームワーク

相手と目的によってフレームワークを用いましょうという話。そういうものがあるなら使えると思いました。ここはテクニックではないですね。

おわりに

あらためて振り返りましたが、ドキュメントの目的を考える、読者の知識レベルを考えるという2点はやはり欠かせません。

その上で本書を読んであらためて気をつけたいことは

  • 論点を絞ること
  • 構造化し、箇条書きは粒度を揃えること
  • 表記ゆれ、誤字、省略を避けること

を守れば良いドキュメントは書けると思いました。

最後に思い出したようにひとつ。僕がドキュメントへのこだわりが強いのは以下の記事であるように引き継ぎが大嫌いだからなんですね。正確には無茶振りな引き継ぎでつらい目にあったからなんですが。過去のこういう記事を書いていました。

take-she12.hatenablog.com

良いドキュメントはエンジニアのたしなみ。今後もソースコードと同じぐらいドキュメント作成能力も鍛えていきましょう。