良いSEは良いドキュメントを書く - いちSEの自己他己IT教育

現在私が所属している部署は
プログラムの開発を協力会社に任せている部分もあるものの、
基本的に我々で設計、開発、テスト、運用まで一貫して行っています
※インフラ系の構築はベンダーへの依頼が多いです

いわゆる「設計はSE、開発はプログラマ」と言った切り分けは
あまり存在していないように感じていますが、
どちらかというとSE色の方が強いです

そんな中で常々感じていることは
"良いSEは良いドキュメントを書く"ということ

この"良いドキュメント"というのが非常に漠然としていますが、
端的に言えば「読みやすい」「論点が明確」ドキュメントのことです

当然ながら誤字・脱字などありません

上述の切り分け通りの感想ですが、
SEにとって一番必要な能力の一つが
このドキュメント作成能力だと考えています

私は設計書だけでなく、
見積条件書や顧客説明資料、手順書やマニュアルなどを作成しますが、
「会心のものが出来た！」と思ってても
上司やチームメンバーに「よくわからない」とバツを食らったり、
顧客を混乱させたりもしました

大体そういう時は
下記の点に関する考慮が抜けていたりします

他の点を考える際に必ず立ち返る最も重要な観点です

口頭で説明すれば5分で終わるものを
練りに練って0.5Dayかけてドキュメントを作る意味はあまりありません

言葉を詰め込みすぎたり、
一つの文章が長すぎたり、
テーマがバラバラだったり・・・

「わかりやすく細かく説明を書こう！」なんて思って書いたら
「何を言いたかったのかよくわからない」と言われたこともありました(ﾉ∀`)

ドキュメントを読んだ人が
「つまりこういうことについて書いてある」とすぐにわかるくらい
内容が明確・明瞭な、贅肉が無い文章を書けているかどうかが大事ですね

私が一番抜けがちなのはここです

顧客に説明するもの・・
上司に説明するもの・・
チームメンバーに説明するもの・・

同じ内容の説明でも
相手が違えば伝え方が違います

作成時はもちろんのこと、
作成し終わった時に
「誰が読むものだっけ？？」と想像しながら見直すことが必要です

マニュアル作成時にはここがポイントになっています

システムの緊急時使用するものと、
テスト時に使用するものとでは
記載する内容の強調する部分や説明が異なってきます

グラフ、表、マトリクス、ツリー・・・

表現方法が適しているのかどうかも
ドキュメントの良し悪しを左右しています

ここはちょっとテクニカルな部分だと思うので
コンサルタントの本とか読むと参考になりますね

この6点は互いに完全に独立しているものではなく、
相互に絡み合っているもので
抜け落ちる時には結構一緒に抜けおちていたりします

SEはコミュニケーションを取りながらする仕事です

そのことからも、良いドキュメントを書けることは
良いSEの条件であることは明確ですね