[3902] エンジニアのためのドキュメンテーション心得

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■装飾山イバラ道［155］
憧れと現実の間

武田瑛夢
< https://bn.dgcr.com/archives/20150512140200.html
>
───────────────────────────────────

いろいろあった大塚家具。うちにも大塚家具で買った家具がいくつかあるけれど、買った当時の15年程前には確かに敷居の高い店だと思っていた。

エントランスを通ると、スーツ姿の店員に何か記入するように促される。病院の問診票のようなものでめんどくさいし、本気の家具購入なのかちょっと見たいだけなのか、事前に調べられる感じだった。

当時はマンション入居のタイミングだったし、家具もまるっと買うつもりもあった。すると、担当さんがついて何を見るにもピタっと寄り添って説明してくれる。丁寧に説明されるとじっくり聞かないと悪い気もするし、なかなか自分たちのペースで見ることはできなかった。良い点悪い点どちらもあったと思う。

●フロアのマジック

当時はフロアを上がるごとにどんどん高級感が増していき、すごい家具もあるものねぇと、気分も上昇して憧れ感に浸ったりした。だんだんと素敵なものは高くても当たり前と思えてくる。その後、カジュアルな階に下りて来ると、やっと現実的な値札を見て安心し購入候補に入れていく。

そこでちょと待て×2の流行の言葉じゃないけれど、高級フロアから下りて来たこのような時が一番危ないのだ。カジュアルフロアは一見安く見えるけれど、本当はそんなに安いわけじゃないことに後々気がつく。

高いフロアは安いフロアに現実感を感じるために、安いフロアは高いフロアに特別感を与えるために、あるのかもしれない。今もフロアごとに何かが違うのだろうか。憧れを抱いた後だから、少しだけ背伸びした現実が受け入れやすい気もする。

当時の私は慎重だったので一回で購入を決めたものは何もなく、結局何度か足を運んでソファとテーブル類を購入した。それらはすべて未だに現役で使い続けているので、物持ちがいい方かとも思うけれど、私のようなタイプの人も多いかもしれない。

今のファストファッションのように、おしゃれで安いデザイン家具を気分で買い替えるというのが、皆本当にできているのだろうか。日本人のなかなか買い替えない、もったいないという本質がそう変わった訳ではないと思うのだ。

IKEAは楽しいし、組み合わせの参考がまるまる置いてあるので助かる。日本人はきっとIKEAの家具も大事に長く使うのではないだろうか。模様替えを機にすべて買い替えたわ！　ってすごくさっぱりしそうだけれど、使える物は残しながら移行するのが日本人の良いところのような気がする。

●歯医者の計算

私が通っている歯医者が移転し、広くなってオシャレになった。壁紙も診察台もピカピカだ。移転祝いの胡蝶蘭がたくさんあって華やかな中、待ち合い室の一部の椅子や傘立ては以前のものを使っていた。

引っ越しでも生き延びた、見覚えのある懐かしいアイテム。患者さんには高齢者も多く、そういうところに安心する人もいるので、もしかして計算かも？　と思えるけれど、先生のセンスはなかなかいいなと思うポイントだった。案外どなたかのお祝いの品だったのかもしれない。待ち合い室ってそういう余計なことを考える時間のある場所なのだ。

大塚家具の新しい店舗にはまだ行っていないけれど、今回の騒動はもしかして宣伝効果ばっちりだったのではないだろうか。お父さんの代に購入した人も、娘の店作りに興味を持ってちょっと見に行く人もいるだろう。

顧客は子や孫のプレゼントに張り切る世代かもしれないし、バブリーな金銭感覚のまま大きな買い物をするのだろうか。壮大な親子喧嘩とも言われていたけれど、壮大な娘自慢だったような気もする。

私も数年ぶりに机でも見に行こうかと思っている。ここ最近はハンズかdinosかIKEAでしかデスク周りのものを見ていなかった気もするし。通販のものも良いけれど、やっぱり現物を見て買う安心感は捨てがたいのだ。

【武田瑛夢／たけだえいむ】eimu@eimu.com
装飾アートの総本山WEBサイト"デコラティブマウンテン"
< http://www.eimu.com/
>

クラッシュ・オブ・クランは未だにタウンホール6のまま防衛設備の増強をじっくりやっている。同じレベルに長居するのは無納金の宿命かな？（笑）ゲームの中では略奪にも慣れたけれど、略奪されるのにも慣れた。力を蓄えている間は負けるのも辛抱だ。


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■Take IT Easy!［51］
エンジニアのためのドキュメンテーション心得

若林健一 / kwaka1208
< https://bn.dgcr.com/archives/20150512140100.html
>
───────────────────────────────────

こんにちは、若林です。今回は、エンジニアのためのドキュメンテーションについてのお話。私がドキュメントを書く時に考えていることを紹介します。

●図、表、箇条書きを使う

テクニカルドキュメントを書く時には、図、表、箇条書きをメインで書きます。「文章を補助するために図を入れる」のではなく、「図で表現できないことを文章で補足する」ぐらいのイメージです。

文章を書く場合もできるだけ箇条書きと体言止めを使い、言葉はできる限り削ります。長大な文章を書くことがテクニカルドキュメントの目的ではありません。その中にあるコアの情報を伝えられればいいのです。

作文しなければ仕事の成果として認められないんじゃないかと誤解しているエンジニアもいますが、エンジニアの仕事は作文ではありません。

これらを心がければ、ポイントの絞れたわかりやすいドキュメントになります。

●適切なツールを使う

エンジニアの書くドキュメントというと、Excelの列を短くしてセルを正方形にし、方眼紙のようにした「Excel方眼紙」を使う人も多いようです。

ワープロソフトの表組み機能や図形描画機能が貧弱で、PowerPointのようなプレゼンテーションソフトがなかった時代に、自由なレイアウトができる方法として重宝されたテクニックだそうです。

しかし、Excelは印刷が画面通りにでない（文字が切れる）ことがあったり、「Excel方眼紙」では罫線や背景色、セルの結合を多用するためメンテナンス性が低いのがデメリット二なります。

代替手段が多数存在するある現在では、目的に応じて適切なツールを使うことも大切です。私がどのような文書にどのツールを使うかを考える時の基準をまとめてみました。

【表計算ソフト（Excelなど）で作成する資料】

・並べ替えやフィルタ機能で欲しい情報だけ抽出できた方が便利な、データが中心の資料

・関数を使って、資料の一部を自動的に作成することができたり、メンテナンスが容易になる資料

・印刷はせずに主に画面で参照することが多い資料

Excelのデータから列挙型のデータを生成するような使い方をすれば、ソースコードの自動生成ツールとしても活用できます。

【プレゼンテーションソフト（PowerPointなど）で作成する資料】

・図や画像を貼り付けることが多く、ページ単位で印刷して利用する資料

・決まったフォーマットの中に記入しなければならない資料（テンプレートを使う）

・表組みを使うが、計算処理やデータの抽出・ソートを行う必要がない資料

私自身は、PowerPointをドキュメント作りに使うことが多くなっています。理由は、印刷に向いていることと、レイアウトが自由で画像や図形が使いやすいことですね。

表組みを使うものも、計算処理やデータ抽出を行わないのであれば、ExcelではなくPowerPointを使っています。

【ワープロソフト（Wordなど）で作成する資料】

・マニュアルのように、文章中心で章立てを組み立てたり、目次をつけることが必要な文書

最近はWordを使うことは減りましたが、マニュアルのように章、節をきちんと組み立てる文書の場合は、ワープロソフトが適しています。

【テキストエディタで作成する資料】

・リリースノートなどの簡易なもの

・Gitなどのバージョン管理システムで履歴管理するもの

Markdownを使えば、テキストエディタだけでも書式付きテキストを書けるようになりましたし、Gitのようなバージョン管理システムで履歴管理できるのもテキストファイルのメリット。リリースノートや、内部向けの開発メモのような規模の小さいドキュメントならテキストでも充分です。

●ドキュメントは、コミュニケーションツールである

ソフトウェア開発プロジェクトにおいては、ドキュメント作成は後回しにされることが多々あります。

しかし、私はドキュメントをコミュニケーションツールのひとつ考えて、小さなドキュメントをたくさん作り、その内容をレビューしながら開発を進めていくという手法を取っています。

ドキュメントを用意せずに会議をするよりも、ざっくりでもよいので書いたものを用意して打ち合わせに臨めば、テーマが明確になり、認識違いや漏れを防ぐことができて、打ち合わせの時間なども大幅に短縮できるなどよいことづくめです。

打ち合わせ結果を書き込めば、記録が確実に残りますので、これを添付資料とすれば議事録に書く内容を大幅に省略できます。

ドキュメント作成をやっかいもの扱いにせず、コミュニケーションツールとして使いこなせば、開発を円滑に効率よく進めることができるものなのです。

【若林健一 / kwaka1208】 kwaka1208@pote2.net
crossroads
< http://kwaka1208.net/
>
< https://twitter.com/kwaka1208
>
< https://www.facebook.com/kwaka1208/
>

CoderDojo奈良
< http://coderdojonara.wordpress.com/
>


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
編集後記（05/12）

●山本兼一「修羅走る 関ヶ原」を読んだ（集英社、2014）。460ページを超える分厚い長編である。関ヶ原の戦況のほぼ時系列に沿ったかたちで、登場人物がタイトル代わりの33の短編が連結されるという構成だ。関ヶ原の主役は石田三成と徳川家康だが、彼らがタイトルに現れるのは三回ずつで、三成の配下である土肥市太郎・市次郎兄弟がそれぞれ四回、三回の登場だから、この長編ではこの二人が主役級といえるだろう。いままで聞いたことのない名前だが。開戦後、それぞれが三成の命で小早川秀秋と毛利秀元の陣にメッセージを届けに行く。ところが、事態は刻々と変わり、最後は二人ともそれぞれ家康の......。

筆者の盟友ともいうべき作家・安部龍太郎が、「石田三成は豊臣家を守る義のために立ったとか、徳川家康は臆病者で計算高い狸親父だったという、江戸時代の軍記物のような紋切り型の設定には、いささか失望させられた」とあとがきの始めに書く。確かにこの物語はそういうスタイルである。しかし、普通の読者にとってはおなじみの、抵抗のない設定であることは間違いない。作家の安部は、この古めかしい設定に違和感を覚える。だが、山本が敢えてそうしたのは理由があった。山本がこの作品を書いていた時期、肺の病に冒され死を意識せざるを得ないほどの状況であった。安部はそれを知っていた。

「作品のテーマが男の生き様と死にあるだけに、山本は関ヶ原の史的解釈に関わる問題をすべて切り捨てた。むしろ一般的な解釈に寄り添ったほうが、読者によりストレートにこの作品を受け入れてもらえると判断したのだろう」と安部は書く。まさしく盟友である。この二人の共通認識は「今の戦国時代史は間違っている」であった。スペインやポルトガルは日本を植民地化する野望を秘めており、信長、秀吉、家康は切支丹対策や貿易政策に頭を悩ませていたのが事実である。そのことを切り捨てた「鎖国史観」や、士農工商の「身分差別史観」により、軍記物や講談のような偏狭な歴史が成立して現在に至る。

「この作品の随所に、修羅場に身を置いた男たちの死に向き合う覚悟と、実際に死んでいく時の思いが描かれているのは、自分の問題として死をとらえていたからにちがいない」。三度言う。まさしく盟友による最高のあとがきである。だから、この物語は講談のような面白さに満ちている。勇猛な男、臆病な男、姑息な男、まっすぐな男、拗ねた男、手柄が欲しい男、逃げようとしている男、戦場にはさまざまな男がいる。山本は間違いなく小説の中の大谷吉継になっている。病を得て、人間のこころが見透かせるようになっている。人としての宿命と人生をぶつけ合う戦場をみごとに描いている。傑作である。（柴田）

< http://www.amazon.co.jp/exec/obidos/ASIN/408771571X/dgcrcom-22/
>
山本兼一「修羅走る 関ヶ原」


●うちもほとんどが大塚家具。三回以上行った。欲しいテイストと質感が同居しているものは大塚家具にしかなかった。担当者はつくが、あまりに長い間見回ってて、担当者さんの他のお客さんが来られたりするので、放置され気味でラッキーであった。質問攻めしていたなぁ、そういえば。なので向こうにとってもラッキーだったのではないだろうか。武田さんのおっしゃる通りで、IKEAやニトリで買っていたとしても、長く使い続けるとは思う。家具は一度買うと捨てにくいし。／「Excel方眼紙」。なるほど。

住宅ローンの続き。元の銀行には計3回。完済の申し入れ、完済手続き、借換当日。

申し入れでは、返済日を伝えて、新しい先へ伝えるための担当者さんの名前を聞く。返済に必要な金額と、直前の通常引き落としについての注意事項を聞く。

完済手続きでは、郵送されてきた書類に署名捺印して持参。固定と変動の二本なので手続きは二倍。契約書類（今回解除）は支店に届きましたよ〜と担当者さんが伝えてくれる。またまた注意事項を聞く。

借換日は司法書士さんと待ち合わせ。新しい借り先からの入金を待つ。入金確認後に契約書類、抵当権抹消用書類をもらい、司法書士さんに手渡し。司法書士さんからは預かり証をもらう。 （hammer.mule）