Pocket

わかりやすい技術文章の書き方

数日前から気になっていたページの一つ。
ちょっと自分の考えを述べてみようかと。

このページは、プログラムやコードなどの主に技術文書を書く方々のために、分かりやすい文章を書くためにはどうすればよいのかについて説明しています。

1.自分が伝えたいこと・訴えたいことを誤解しないように相手に読んでもらうにはどうするべきか。
2.文章を書くにあたって知っておくべきルールは何か。
3.文章を書く前にどのような手順を踏めば、分かりやすい文章を作れるか。

などについて参考にしていただければ幸いです。

実はこれ、プログラムやコードなどの主に技術文書を書く方々に向けておりますが、ものつくりにも当てはまります。
建築でいえば、設計図、図面など。

ここのブログを見ている方は、恐らくWeb関係が多いのでは?
ということで、ピックアップすると、ファイル名などの命名規則サイトマップ(階層の整理)、CSSなどの詳細設計書、W3Cに引っ掛かってもこれは問題ないといける参考文献をまとめること。
チェックリストデバックリスト画面変移図、DBを使っているならばデータベース詳細項目(intなのかcharなのか16進とか)などなど。
単体検証全体検証パターンリスト最終確認完了しましたよの書類。(ここまで来ると過去の仕事内容が思い浮かびます。w)

クライアント様からそこまでは要求はされないはずですが、大きなプロジェクトになればなるほど、設計始める前にこのような基本的な情報を制作者たちに教える必要があるんです。これが標準化されればもっと嬉しいことなのですが、そんな時間ないよ。ということで、作ったら作ったで終わり。次の仕事。ってなる。

顧客からのクレーム対応マニュアルがあるところはたいてい、プロジェクト進める前の準備(標準化)はされているはず。w

で、あんたは今まで納品した仕事で説明書とか作ったの?という質問がきそうだが、実際に作ってました。
しかも、自分から手が離れてからはしばらく安定するまではサポートしますが、基本的にはドキュメントにすべて書いてあります。
相手が、Webの知識がない人でもわかるような資料です。

一番手っ取り早いというか、これは間違いようがないというのは
画面のキャプチャーを添えた説明書みたいなもの。

みなさん、見ているはずです。
電気機器を購入して付いてきた説明書
分厚くて読まずに捨ててしまう説明書

あれを参考にすれば技術文書なんてつまずくことなく、書けます。ほんとに。

日本語から英語にするというのは、至難の業になりますが、技術屋としては避けられない道です。

過去の事例とかは詳細というか、どの部分を担当したか?キャプチャー、日数とかは明確にされているが、中身は?となると、???になってしまう。
あー、これ担当した人はもういないからなぁ。。。
(Web業界では人の流れも速いみたいってこの業界に足つっこんでみて実感しました。)

それじゃー、意味ないんです。

あと、安さを求めて海外に発注する方もいらっしゃるのでは?
どこをどうすればどうなるのか?というのもドキュメントとして残す必要もあるということです。

「ソース見ればいいじゃない。」

それでいいんです。けど、設計書があれば、もっと時間短縮できて効率のいい仕事ができると思います。

ここをこうした理由はこういうことになってしまうから。By hogehoge
この一言でもぜんぜん違うんです。
「え?なんで?」と思ったら自分で考えてみて、それでも趣旨が伝わらなかったら聞けばいい。

本当にread_meだけでどれだけ助かることか。。。

フリーソフトの場合、必ずreadme.txtが入っています。もしくは、URLのリンク先。
どう使えばいいのかわからなくなった場合とか、どのexeファイルが起動用なのか?など、簡単な説明書。

このreadme.txtも意味があって、copyrightみたいな感じでもあります。

自分の場合、ほとんどのソース(phpなどのプログラム関係)はヘッダーに自分のサイン、変更履歴を残すようにしています。あと、バージョン管理!
あー!バージョン管理!かなり重要です。

なんか余談になってしまいましたが、まずはお手元にある電気機器の説明書を仕方なくペラペラと見てください。
2種類あればかなり比較できるかも?
説明書なんてねぇ!という方は、次買いたい電気機器のオフィシャルホームページに行っていただき、発売前だったら新製品になる前の型の説明書をダウンロードしてみてください。(PDFファイルで用意されています。)

こっちはこういう順番なのに、こっちはどうして?とかいろいろと違いが見えてくると思います。

参考文献を見るのもいいですが、身近なものから得た方がかなり親近感沸くと思います。

だって、第3者でもわかる説明をしているのだから

From xxxYukihiroxxx

P.S
設計より検証する時間の方が時間がかかります(チェックリストがあればあるほど)。
つまり、設計時間<<<<<検証時間となります。
設計時間=検証時間になる方法がある場合、技術屋さんに教えてくださいませんか?

Pocket

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください