ドキュメント と コーディング
仕事で凄く久しぶりにドキュメント作成をしています。
ここで言う「ドキュメント」とは、ソフトウェアの仕様書とか説明書とかの事だと思って下さい。
社内案件だと、仕様も定まらないまま、ずるずると運用開始になって、そのまま使いながら仕様変更と追加を繰り返すというケースが多いので、ドキュメントなんて作り様が無いというか、作っても無駄というか。
だって書いた端から内容が変わるんですから、誰もあてにしないし、見もしないのですよ。
当然、そんなもの作るのに時間をかけたくないわけです。
ただ、それはそれとして、作らねばならないとなると「どうせ作るなら少しでもマシなものを」と考えるのもまた人情と言いますか。
あるいはブログ書きの習い性と言いますか。
文章は短く、箇条書きで。
内容は主語と目的語を明確に。
複雑な内容は流れを先ず示して、詳細は別途。
変更が予想される箇所は別途記述にして、そちらを参照してもらう。
読み手が疑問や不明点を持った際に問い合わせる先を提示しておく。
図解は正義。
…etc.
嫌だ嫌だと思いつつも、書き始めるとついついあれこれと考えてしまいますね。
