技術文書の書き方、心がけたい6つのポイント
こんにちは、
拙作ブログをご覧いただきありがとうございます。
今回は、技術文書の書き方です。
といっても、
難しいことを書くつもりはありません。
私は技術屋として、
大手鉄鋼メーカーに勤務していました。
そこで、
制御用コンピュータシステムの
エンジニアリング(建設)をやっていました。
いわゆるコンピュータ屋です。
その経験をいかして、
技術文書の書き方について、
紹介したいと思います。
いわば、
実体験から得たノウハウのようなものです。
何かの参考になればと思っています。
題して、
技術文書の書き方、
心がけたい6つのポイント
です。
6つのポイントとは下記です。
1)正確、かつ漏れなく。
2)分かりやすく。
3)読みやすく。
4)「基本的考え方」が大事。
5)思考過程を残す。
6)改訂履歴も残す。
では、さっそく見ていきましょう。
1.文書は正確、かつ漏れなく
技術文書に限らず、
すべての文書は正確性と完全性が重要です。
1)正確に。
とくに技術文書では正確さが求められます。
というのは、
その技術文書がもとになって、
次の研究開発や技術開発が行われるからです。
多少分かりににくくても、
正確さに心がけてください。
2)漏れなく。
これも大事です。
技術文書は成果報告ですので、
技術成果をすべて書くことが求められます。
仮に、
その技術成果が不満足だったり、
不本意な結果に終わったとしても、
結果をすべて書いてください。
ただし、書き方には一工夫が要ります。
基本となる結果と副次結果とを分けて、
誤解されないようにしましょう。
このへんは後述します。
2.分かりやすく
この「分かりやすさ」も、
技術文書に限ったものではありません。
一般の文書にもいえます。
2-1.分かりやすくを勘違いしないように
分かりやすくとは、一般の読者に対してです。
特定の専門技術者だけが、
分かっていてもダメです。
大抵の技術者は、
ここのところを勘違いしています。
やたらに、
専門用語を使いたがる傾向があります。
私にいわせれば、
専門用語を使いたがる人にかぎって、
自分の技術に自信がない人が多いようです。
あえて難しい用語を使って、
自分を偉くみせようとしているのではないでしょうか。
それとも、
読者を煙に巻こうとしているのでしょうか。
いずれにしても、
本来の技術文書の目的・意味を逸脱しています。
2-2.平易な言葉を
いずれにしても、
専門用語の乱用は、
技術文書の目的を逸しています。
百害あって一利なし
です。
最悪、専門用語を使う場合は注釈を入れてください。
可能な限り平易な言葉で書いてください。
技術文書イコール難しい文書。
これでは困ります。
2-3.簡潔に
「読みやすく」の極めつけが、
「簡潔に」です。
文章がくどいと思考が混乱します。
言いたいところを簡潔に書きましょう。
いくら正確な技術文書でも、
読んでもらえなければ意味がありません。
どんな文書でも、
読まれて「なんぼ」です。
3.読みやすく
これは、
多少前項とダブりますが大事なことです。
とにかく、
「読みやすく」に徹してください。
3-1.ストーリーに工夫を
これも普通の文書と同じです。
全体のストーリーに工夫をしてください。
◆起承転結が基本ですが・・。
起承転結が基本となるのは技術文書でも同じです。
ただ、少しだけ違うところがあります。
以下は代表的(典型的)なストーリーです。
①概要(緒言ともいいます)
※この概要に「結論」を書きます。
②目的
③前提条件
④設備仕様(実験設備を含む)
⑤結果
⑥結果の考察
⑦課題
⑧まとめ(結言)
ポイントは、
文書の結論を冒頭に
持ってくるところです。
3-2.図、表、写真を多用
分かりやすくする方法の具体例は、
図、表、写真を多用することです。
とくに、図は有効です。
(上図参照)
あとから口頭で説明するときでも、
図を中心に行ったほうが、
分かりやすくなります。
また、写真も有効です。
写真は図より、
さらに「リアル感」が増します。
このように図や写真は、
インパクトを与えるのに一番有効な手段です。
3-3.アクセント(メリハリ)も
文書にアクセント(メリハリ)も大切です。
上記の図、表、写真もその一つですが、
それ以外に、
見だしや文章にも一工夫してください。
◇見だし:文字の大きさ、色を変える。
◇タイトル:一目で分かるようにする。
◇文章:強調したいところの文字を変える。
(大きさ、色、字体など)
4.「基本的考え方」が大事
ここからが、
技術文書特有の心得になります。
まず「基本的考え方」ですが、
これは、技術文書の対象となった作業(研究や開発)の
基本的な考え方を記載するものです。
別な言い方をすると以下のようになります。
①コンセプト(概念)
②フィソロフィー(哲学)
何だかさらに分かりにくくなりましたね。
では、例で説明しましょう。
【例】システム構築
基本的考え方のサンプル1:コストミニマム
基本的考え方のサンプル2:最新技術の導入
これで分かりましたよね。
ようは、技術開発などにおいて、
どこに力点を置くかを明確にすることです。
ここがハッキリしていないと評価ができないからです。
この「基本的考え方」は、作業中(技術開発中)の、
「道しるべ」となるものです。
よって、
もっとも重要なものとなります。
ただ、
この「基本的考え方」は、とかく忘れがちです。
作業者の頭の中にはあるのでしょうが、
文書として残っていません。
これは不幸です。
問題です。
せっかくの技術文書にコンセプトがないのは、
家でいうと土台がないようなものです。
是非、記入するようにしてください。
5.思考過程を残す
次に技術文書で大事なものが思考過程です。
この思考過程も忘れがちなので注意してください。
5-1.思考過程とは
思考過程とは、結論に至った過程です。
①複数案を考案した理由や背景。
②その案の中から、
最終案になるまでの経緯、理由。
こういうものを思考過程といいます。
5-2.なぜ忘れるのか?
思考過程の記述は技術文書から忘れがちです。
それは、結果だけに気持ちが行くからです。
結果、イコール、報告対象
となるからです。
結果だけが評価されるからです。
5-3.なぜ大事なのか?
思考過程の大切さは下記にあります。
1)技術伝承
この思考過程は、まさに「技術」です。
あるいは、
ノウハウ(知恵)
といってもよいでしょう。
これを第三者に伝承する必要があります。
(自分自身への伝承という意味もありますが)
技術伝承は、技術開発では大事な使命です。
2)自己反省、自己確認にも
思考過程を書き留めることは、
自己反省、自己確認にもなります。
つまり、書くことによって、
頭の中が整理できるのです。
本人がどういう考えや思考で結論に至ったかは、
文書にしないと分かりません。
だって、思考過程ですので目に見えませんから。
だから、実際に作業をした本人さえも忘れます。
これは非常に勿体ないことです。
不幸なことです。
折角の思考が日の目を見ないことになります。
これでは技術の伝承は出来ません。
それどころか自己反省もできません。
あなたの苦労は報われません。
これでは本当の成果の半分も残りません。
6.改訂履歴も残す
最後の心得は「改訂履歴」です。
他の文書でもそうでしょうが、
文書の完成後に改訂が発生します。
改訂理由にはいろいろとありますが、
一番大事なのは、知見の追加、変更です。
つまり、追加の実験や仕様の追加変更です。
とくに、プロパー設備ではよくある話です。
この履歴を技術文書に残しておきます。
【具体例】
改訂01)○○年○○月○○日
××仕様の追加に伴い、△△を追加。
上記を時系列に列挙しておきます。
これも技術の蓄積の一つです。
技術伝承になります。
7.まとめ
どうでしたか。
技術文書のポイントがお分かりになったでしょうか。
なんとなく分かったとしても、
それが自分のものになるまでには、
相当の時間がかかります。
7-1.実務だけでも大変なのに
正直いって技術文書まで手が回りません。
設備が完了した時点で、エネルギーを使い果たしています。
「結果の報告なんて適当でいいや」
「設備さえ動けばいいじゃん」
となりがちです。
私も、かつてはそうでした。
7-2.残ったのは目の前の設備だけですか?
しかし、技術文書が ”なおざり” になると、
あなたの汗と苦労は、
目の前の設備だけとなります。
目の前の設備に、
あなたの汗が残っていますか?
あなたの苦労がみえますか?
あなたの足跡は、
技術文書しかありません。
その技術文書がないと、
後に続く技術者が、
あなたと同じ苦労をしなければなりません。
そこのところを、
よく考えてくださいね。
最後までお読みいただき、
ありがとうございました。
【関連記事】
※更新履歴※
【更新】2020年1月10日、23日、28日、2月19日、26日、3月20日、5月20日、10月6日、2021年1月25日、7月12日、2022年7月29日
少しだけ校正させていただきました。
【更新】2019年9月5日
「目次」を追加しました。
これで少しは読みやすくなったと思います。
※CMリンク※
「わかりやすい」文章を書く全技術100
理工系の技術文書作成ガイド
入門 考える技術・書く技術――日本人のロジカルシンキング実践法
考える技術・書く技術―問題解決力を伸ばすピラミッド原則
技術系英文ライティング教本: 基本・英文法・応用
技術翻訳のチェックポイント―技術文書の作成と評価
入門 考える技術・書く技術
技術士第二次試験 合格する技術論文の書き方 (国家・資格試験シリーズ 382)
10倍速く書ける 超スピード文章術
技術文書の書き方: Wordで作成してKindleで出版する
学びを結果に変えるアウトプット大全 (Sanctuary books)
即効! 成果が上がる 文章の技術 (アスカビジネス)
超・箇条書き―――「10倍速く、魅力的に」伝える技術
理科系の作文技術 (中公新書 (624))
英文技術文書の作成+用語集 ~開発・製造の実務英語~