検索お知らせログイン「住まいの地盤診断[軟弱地盤を見抜く]」講座を公開しました。(2020/2/10)「DXプロジェクトの進め方[要件定義]」講座を公開しました。(2020/2/3)「開発ドキュメントの悪文修正術[抽象的な表現]]」講座を公開しました。05:00今回は、ドキュメントの骨格の中に埋めていく文章(段落)や図表の構造を考える。これらはもともとツリー構造ではないが、ツリー構造という視点を持つことで分かりやすい説明が可能になる。前回の事例の続きを使って、説明していく。事例は、顧客に納品した自社システムの応答が遅くなったことへの対策を求められたというものだ。応答が遅くなった原因は、DB処理のパフォーマンスの低下だった。その根本原因は、データ量の増加に比例して処理時間が増えたことと、後から追加された他社システムのデータ更新処理待ちが多発していることだと分かった。それらの原因への対応策として、それぞれに2つの打ち手が案として挙がった。実際に対策を実行に移す前に、どの原因に対応すべきか、どの対策を打つべきかを判断する必要がある。どの原因に対応すべきかを評価した結果が図1だ。リリース時と現時点での所要時間の内訳を表した帯グラフである。図中の赤い数字と矢印については後述する。図1●パフォーマンスの比較[画像のクリックで拡大表示]こうした図は、提示するだけでは作成意図通りに読んでもらえるとは限らない。正確に伝えるためには、図表が表現していることの意味をテキストで記述する必要がある。以下に図1を説明した例を示す。この図は性能低下を指摘されている機能について、処理時間の内訳をリリース時と現時点で比較したものです。データサイズに依存しない処理時間(1)がほとんど増加していないのに対し、データサイズに依存する処理時間(2)は大きく増加しています。リリース時に想定していなかった、他社システムによるデータ更新処理待ち(3)が非常に大きな割合を占めています。このことから、今回の性能低下の主要因は他社システムによるデータ更新処理待ちであると考えられます。このテキストを、文書アウトラインとしてツリー構造で図示すると図2のようになる。図1の赤い数字と矢印を対比しながら確認してほしい。図2●図1を書き下したアウトライン[画像のクリックで拡大表示]文1で何を表現しようとしている図なのかを示した後、文2~4で各内訳の説明を行い、文5でそれらを根拠とした結論を示している。図には事実データのみが示され、❺に対応するものはない。図3●施策の検討[画像のクリックで拡大表示]次に、どの対策を打つべきかを評価した結果が図3だ。施策ごとに複数の指標の値を示した表である。内容をテキストで記述すると、以下のようになる(結論は示していない)。この表は案として出された各施策について、効果、実現性、コストの観点から検討した結果です。データサイズに依存する処理時間を短縮するためのDB処理の高速化とDB処理の並列化は、ある程度の効果が期待でき、どちらも当社で実施できる施策です。並列化は、高速化よりコストがかかります。データ更新処理待ち時間を短縮する2つの施策は、大きな効果を期待できますが追加の検討が必要です。共通データ参照をなくすアプローチのほうは、処理の性質上、実施不可というのが当社技術部の見解です。他社システムの処理改善については、実現性、コストともに当社内では十分な検討ができず、担当社に確認する必要があります。パラグラフライティングで構造化この記述をアウトライン形式で表したものが図4で、ツリー構造になっている。図の内容を分かりやすく説明するには、図の全体像を示した上で、ツリー構造にまとまるように段落を組み立てていけばよい。図4●図3を書き下したアウトライン[画像のクリックで拡大表示]段落をツリー構造で整理しているのは、意識的にそうしている。テキストの記述力は強力なので、指示語などを使えば順序良く文が並んでいなくても内容を表現できる。読み手が最初から順に読んで理解できるようにするには、適切なまとまりと順序で文を並べるべきだ。ここでは、「パラグラフライティング」と呼ばれる書き方の手法の指針を利用している。この手法は欧米で意図を明確に伝えるために広く指導されている書き方だが、日本ではあまり知られていない。重要な指針は、まず文のまとまりをパラグラフと呼び、1つのパラグラフに1つのトピックを書くことだ。大切な文を1つ決め、トピックセンテンスと呼んで最初に示す。その文を支えるサポートセンテンスとして、他の文を後に続ける。この指針で書いていくと必然的に、トピックセンテンスを親に、サポートセンテンスを子にしたツリー構造になる。ここまでの解説で、ドキュメントは全体の構造から図表に至るまで、ツリー構造に代表される構造という視点で分析、再構成できることを理解してもらえたと思う。資料の構造を意識することは、情報をどういう手順で提示すれば、相手が無理なく理解でき、こちらの話に納得してもらえるのかを、情報提供のプロセスとして設計することなのだ。特化した関連会社として同社を設立、初代社長に就任。現在は、代表を退き顧問として同社社内の人材育成を主に活動しつつ、社外の技術者のスキル向上のために勝負ドキュメント研究所を開設。pp.16-17記事は執筆時の情報に基づいており、現在では異なる場合があります。Reserved.このページに掲載されている記事・写真・図表などの無断転載を禁じます。掲載している情報は、記事執筆時点のものです。