サウスポーなエンジニアの独り言

サウスポーなエンジニアが日々感じた、気づいた、学んだことを徒然と書いています。

旧館より 考え方

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

投稿日:2010年1月24日 更新日:


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

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

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

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

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

1:「都度」確認する

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

2:視点を変える

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

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

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

-旧館より, 考え方

執筆者:


comment

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

関連記事

仕事が10倍速くなる最強の図解術[読書感想]

仕事が10倍速くなる最強の図解術 報告書やプレゼン資料を作成する際に、図解化することで抜けや漏れが無いか(MECE)、また説得力のある論理構成になっているか?を確認し、質の良いものを造り出しましょうと …

ドキュメント修正の大事さ

プロジェクトメンバー、リーダーとしての振り返りで毎回思っては実現できていなかったことを備忘録として書いておきます。 言いたいこと 仕様書等のドキュメントの作成/修正が後付けになったりして、ソースコード …

個人目標をオープンにするのってどうでしょうか

組織の目標とは別に、個人も目標を立てて、定期的…半期に1度など…にそれを評価する仕組みになっています。 目標の例として「○○PJのリリース日を遅延しない」「情報処理試験に合格する」や「○○という技術に …

あるリーダーFさんのこと

ふと週末に近所を散歩していたら、クラブ活動中の母校(中学校)の学生を見かけて思い出したことです。 これまで自分が出会ったリーダーで、強く印象に残っている一人が中学校時代の先輩でした。 #中学時代のこと …

雛形やテンプレートは現場の役に立って「ナンボ」

ある程度の組織にはPMO(プロジェクト・マネジメント・オフィス)や「品質標準化グループ」のような部署があり「設計書のフォーマットはこういうのを使ってください~」「レビューではこのチェックリストに沿って …

ギルドワークスの現場コーチ。
「正しいものを正しくつくる現場を増やす」ことを目指している現場コーチ。認定スクラムマスター(CSM)。
様々な規模のSIerでのシステム開発を経て今に至る。
DevLOVE関西を主催。