月別アーカイブ: 2010年1月

ドキュメントを書くために気をつけていること

#ソース元は「誰にでも伝わるSEのための文章術-第6回 読みやすい文章の極意は「修飾語」にあり」です。

「あぁ、そうやなぁ」と思うようなことが、分かりやすい例とともに記述されています。
今まで書いたドキュメントを見直しても、NGケースに当てはまるものが1つはあるかと思います(苦笑)。
で、この記事を読んで思ったことをつらつらと書いてみます。

システム開発などの設計書を書き上げた(書いている途中含む)後、レビューまでに自分でどういう点に気をつけているでしょうか?
できれば、上記記事にあるレベルはクリアしたいものです。結果的に完全にクリアできていなくても、その視点で見ておくことでも意義があると思います。

レビューの大きな目的の1つは、「記述内容に齟齬がないか?」を確認することです。
そのレビューに、上記記事にあるNGケースが多くあると、目的に行き着く前にレビューアとして「ここの解釈はAですか?Bですか??」と確認をしたりして、時間が余計にかかってしまいます。時間だけでなく、集中力も使ってしまいます。

以下は、そういうドキュメントを書くために、気をつけていることです。

1:「都度」確認する

一気に書き上げた場合…特に勢いに任せた場合、NGケースにひっかかるような内容になることが多い気がします。
一段落書いたら、先に進む前に、それまでの段落と今回書いた段落の整合性、単語の齟齬がないか確認します。
最後まで書き上げてから、チェックして統一性を取るのは、量もあるでしょうし大変です。
#テストファーストやTDDと同じ感覚で、ちょくちょく確認しましょうというものです。

2:視点を変える

文章を書くお約束で「ラブレターは一晩寝かせてから(読み直して)送る」というのがあります。
書き上げた直後は脳内補完がかかってしまい、その文章の確認が甘めになってしまいます。

なので、一息置いて…これが「一晩寝かせて」ですが…レビューアや受け取り側の視点で読み直してみます。
#当たり前のことですが、これらを含めた上で「ドキュメントを書き上げる」工数を見積もるのが前提です。

誤字・脱字はチェックできているなら、もう一歩進んで、この記事にあるポイントもチェックして、本来のレビューの目的を達成できるように心がけたいものです。

ワークフローシステムが意味がない時

社内にあるワークフローシステムを使って事務処理をしていた時にふと思ったことです。

例えば、開発プロジェクトでサーバなどのハードウェア器機を調達する必要が出てきたとします。
それは、当然個人で買うわけでなく、プロジェクトの予算…部門、ひいては会社のお金…で買うのですが、その際に直属の上司を初め、経理などの関係部署の承認を得る必要があります。

その承認を得る人/組織の立場によって見るべき観点も違ってきます。
例えばプロジェクトマネージャであれば「このPJにおいて、それが必要か?他に代替できる術はないか?」と、部門長であれば「他のPJ(部門全体の予算)との兼ね合いで大丈夫か?」はたまた、経理部門であれば「その見積方法、金額妥当か?(経理の)手続き上、不備がないか?」などなどです。

そのため、、承認を依頼した結果が…「プロジェクトマネージャ視点では承認だが、経理的には(金額が妥当でないので)否認になった」というのは分かります。

でも、明らかな誤字/脱字、論理的におかしい理由が記述された承認依頼を最初の承認者の承認後、上位の承認者から、「(誤字/脱字による)否認」をされるような状況は「その最初の承認者は何をチェックしていたん?ちゃんと見ていた??」と思うわけです。

(複数の承認者による)ダブルチェックが働いている証拠でもありますが、一方で「闇雲に承認してるだけなら意味がないよなぁ」と思ったわけです。
#承認する側の立場の「誤字/脱字レベルは申請者がキチッとしれくるのが当たり前だろ」と言うのも分かりますが…

※注意:この記事は旧サウスポーなエンジニアの独り言から移行し一部修正したエントリです。

Photo credit: sachac via VisualHunt / CC BY