わかりやすい技術文書へのアプローチ：技術文書の「書き方」－共通のポイントと各種文書への応用－

<BODY BGCOLOR="#ffffff" LINK="#ffffff" VLINK="#ffffff"> <P> <img border="0" src="fig-t00/gb-bar-introduction.gif" width="540" height="26" alt="わかりやすい技術文書へのアプローチ"><BR> <img border="0" src="fig-t00/tgb00-ttl.gif" width="570" height="150" alt="技術文書の「書き方」－共通のポイントと各種文書への応用－"><HR> <H1 style="line-height: 150%"> <B><font color="#800000">プログラム開発者向け仕様書</font>の書き方<br> </B> <span style="font-weight: 400"><font size="5" color="#000080">－「読者の視点」と「製品の動作」で構成する－</font></span></H1> <div align="center"> <center> <table border="0" cellspacing="0" width="75%" style="border-collapse: collapse" bordercolor="#111111" cellpadding="0"> <tr> <td width="10" bordercolor="#000000" bgcolor="#008080" bordercolorlight="#FFFFFF" bordercolordark="#FFFFFF">　</td> <td bordercolor="#000000" bgcolor="#FFFFFF" bordercolorlight="#FFFFFF" bordercolordark="#FFFFFF"> <p style="line-height: 150%; margin-top: 2; margin-bottom: 0; margin-left:10; margin-right:10"> メーカが他社の開発技術者向けにエンドユーザ向けの製品を構成する要素（部品あるいはプログラムコンポーネント）の仕様と使い方を文書で解説する場合があります．あるいは，システムを構築・管理する技術者向けにソフトウェアの詳細な動作と使い方を文書で提供する場合があります．いずれも，先に述べた「機能仕様書」とも「エンドユーザ向けの製品解説」とも位置付けが異なる文書です．当セクションでは，プログラム開発者向けにプログラムコンポーネントを提供する際の文書を例にして先のエンドユーザ向け製品解説・マニュアルあるいは機能仕様書との違いおよび表し方のポイントを解説します．</p> <ul type="circle"> <li><p align="left" style="line-height: 150%; margin: 0 10"> <font color="#008080"> 本セクションでは，読者対象を明確にするために前セクションの「製品解説・マニュアル」の表記を「エンドユーザ向け製品解説・マニュアル」とします．</font></li> </ul> </td> </tr> </table> </center> </div> <HR> <H3>「<B><font color="#800000">プログラム開発者向け仕様書</font></B>」の<font color="#800000">執筆者</font>と<font color="#800000">読者</font></H3> <p style="margin:1 10; line-height: 150%; "> ここで述べる「プログラム開発者向けの仕様書」の執筆者は，アプリケーションソフトウェアを開発するのに必要なソフトウェアのパッケージ（ソフトウェア開発キット，通称SDKに類するパッケージ）を提供する<font color="#800000">メーカの技術者</font>です．対して，読者はエンドユーザ向けのアプリケーションソフトウェアを開発する<font color="#800000">プログラマ</font>です．執筆者も読者もプログラム言語の知識を有する技術者です．しかし，読者は執筆者の「論理」で開発かつ命名されたプログラムコンポーネントの動作と使い方を理解し，これらを組み合わせてエンドユーザ向けの製品の機能を開発しなければなりません．</p> <ul> <li> <p style="line-height: 150%; margin-top: 0; margin-bottom: 15"> <font color="#000080"> 前述の「機能仕様書」は，これから製品を開発する技術者間で仕様を周知するための文書です．したがって，その「主たる視点」は「（製品をともに開発する）私たち」です．同じように「仕様書」とよびますが，ここで述べる「プログラム開発者向け仕様書」とは位置付けが大きく異なります．</font></p> </li> <li> <p style="line-height: 150%; margin-top: 0; margin-bottom: 15"> <font color="#000080"> 混同を避けるために，「機能仕様書」を「要件定義書」もしくは「開発仕様書」，対して「プログラマ向け開発仕様書」を「プログラム開発ガイド」とよぶメーカもあります．</font></p> </li> </ul> <p style="margin:1 10; line-height: 150%; "> 執筆者が提供するプログラムコンポーネントは，主たる用途を想定して開発されていても，その組合せ方はプログラム開発者がエンドユーザ向けの製品に実装する機能によって決まります．プログラム開発者が目指すのは，プログラムコンポーネントの動作によりエンドユーザが必要とする機能をいかに実現するかです．</p> <hr> <H3>「<FONT COLOR="#800000">エンドユーザ向け製品解説・マニュアル</FONT>」と「<B><font color="#800000">プログラム開発者向け仕様書</font></B>」の違い</H3> <p style="margin:1 10; line-height: 150%; "> “使う人”が読者という点では，両者の「主たる視点」は「<font color="#800000">あなた</font>」です．ただし，「製品の動作」を表す際にエンドユーザ向けの製品解説・マニュアルでは「ユーザによる操作の結果」として表すのが一般的ですが，プログラマ開発者向け仕様書では「<font color="#800000">プログラムコンポーネントの定性動作</font>」として表すのが通例です．</p> <ul> <li> <p style="line-height: 150%; margin-top:0; margin-bottom:15"> <font color="#000080">プログラマ開発者向け仕様書では，「（ある条件で）＊＊クラスは＊＊＊を取得する」など「主語-目的語－述語」で表します．</font></p> </li> </ul> <p style="margin:1 10; line-height: 150%; "> エンドユーザ向けの製品解説・マニュアルとプログラム開発者向けの仕様書の違いは，“ブラックボックス”の外側と内側の違いであると言えます．プログラム開発者向けの仕様書では，ある機能を構成する際に必要な“複数の”プログラムコンポーネントの動作の関係（ブラックボックスの内側）が主たるテーマです．対して，エンドユーザ向けの製品解説・マニュアルでは，ユーザから見た“一つの”製品（いくつもの機能が集約された）の動作が主たるテーマです．</p> <ul> <li> <p style="line-height: 150%; margin-top: 0; margin-bottom: 15"> <font color="#000080"> 携帯電話のソフトウェアを開発するためのSDK（プラットフォーム，ライブラリなど）があるとします．プログラマは，複数のプログラムコンポーネントを用いてアプリケーションプログラムを作成して機能を実現します．この際，それぞれのプログラムコンポーネントは「動作」としてとらえます．したがって，プラットフォーム上では数百あるいはそれ以上にさまざまな動作の主体によるいくつもの動作が実行されると言えます．</font></p> </li> <li> <p style="line-height: 150%; margin-top: 0; margin-bottom: 15"> <font color="#000080"> 対して，エンドユーザが携帯電話を使う際，「動作の主体」は液晶画面が基本です．その他の動作の主体はいくつかのランプとスピーカにすぎません．キーあるいはマイクは入力部であった，操作の対象です．したがって，「選択すると，液晶画面が＊＊設定画面を表示します」とその都度とはせず，「選択すると，＊＊設定画面が表示されます」と受け身文で表します．</font></p> </li> </ul> <p style="line-height: 150%; margin-top: 0; margin-bottom: 15" align="center"> <img border="1" src="fig-t00/tgb0006a.jpg" width="480" height="360" alt="位置付けの違い－「動作の主体」の種類・数－"></p> <hr> <H3><FONT COLOR="#800000">プログラムコンポーネント</FONT>の「<FONT COLOR="#800000">動作</FONT>」の表し方</H3> <p style="margin:1 10; line-height: 150%; "> 上述のように，エンドユーザ向けの製品解説・マニュアルでは，「動作の主体」となる製品は“ほぼ一つ”に集約されます．対して，プログラマ開発者向け仕様書では<font color="#800000">「動作の主体」は多数</font>（場合によっては数百）です．この違いから，「主たる視点」が「（“使う人”である）あなた」であっても，製品の動作の表し方が異なります．</p> <ul> <li> <p style="line-height: 150%; margin-top:0; margin-bottom:15"> <font color="#000080"> たとえば，「表示」という動作を取り上げても，エンドユーザ向けの製品ではその「動作の主体」はとくに明示しなくとも製品本体です．したがって，「製品が＊＊を＊＊に表示します」とせず「＊＊に＊＊が表示されます」で済みます．一方，プログラマ開発者向け仕様書では｢表示」の「動作の主体」はいくつもあります．したがって，「ABCクラスがabcを表示します」，「DEFクラスがdefを表示します」と表す必要があります．</font></p> </li> <li> <p style="line-height: 150%; margin-top:0; margin-bottom:15"> <font color="#000080">しばしば，エンドユーザ向けの製品解説・マニュアルで「HIJ画面にhijが表示されます」と「HIJ画面がhijを表示します」が混じっているのを見かけます．これは，技術者がプログラム開発者向けの仕様書との位置付けの違いを考慮せず，あいまいに混用していると言えます．</font></p> </li> </ul> <p style="margin:1 10; line-height: 150%; " align="center"> <img border="1" src="fig-t00/tgb0006b.jpg" width="480" height="360" alt="主な文体と動作の表し方の違い" vspace="15"></p> <p style="margin:1 10; line-height: 150%; "> 整理すると，プログラマ開発者向け仕様書では主たる視点をエンドユーザ向け製品解説およびマニュアルと同じく「あなた」とし，製品の動作を表す際は機能仕様書と同じく「製品の定性動作」で表すのが適当です．</p> <ul> <li> <p style="line-height: 150%; margin-top:0; margin-bottom:15"> <font color="#000080">プログラム開発者向けの仕様書は，機能仕様書に準じた見出しで構成されるのが一般的ですが，読者にとって「何であるか／使うことの必要性・有効性」を述べるには製品解説およびマニュアルに準じた文体で表すのが適当です．ただし，先に述べたように動作の主体が複数ありそれぞれが相互に作用する関係にあるため，製品の動作を表す際は「主語－（目的語）－述語」とした主語を明確にした能動文で表すのが原則です．</font></p> </li> </ul> <table border="1" cellpadding="3" cellspacing="0" bordercolor="#000000" width="72%" style="border-collapse: collapse"> <tr> <td width="25%"> <p style="line-height: 150%; margin-top: 5; margin-bottom: 5" align="center"> 文書の種類</td> <td width="9%" align="center" bgcolor="#CCFFCC"> <p style="line-height: 150%; margin-top: 5; margin-bottom: 5">主たる視点</td> <td width="66%" align="center" bgcolor="#CCFFFF"> <p style="line-height: 150%; margin-top: 5; margin-bottom: 5">製品の動作</td> </tr> <tr> <td width="25%" bgcolor="#FFFFCC"> 機能仕様書</td> <td width="9%" valign="top"> 私たち</td> <td width="66%" valign="top"> ある条件<font color="#000080">（仮想のユーザの操作／事象の発生）</font>の製品の定性動作<font color="#008080">［（製品は）-を-する]</font></td> </tr> <tr> <td width="25%" bgcolor="#FFFFCC"> エンドユーザ向け製品解説およびマニュアル</td> <td width="9%" valign="top"> あなた</td> <td width="66%" valign="top"> 操作の結果<font color="#008080">［（あなたが）すると，＊＊＊が－される／-する／-になる］</font></td> </tr> <tr> <td width="25%" bgcolor="#FFFFCC"> プログラマ向け仕様書</td> <td width="9%" valign="top"> あなた</td> <td width="66%" valign="top"> ある条件<font color="#000080">（例：イベントの発生）</font>でのプログラムコンポーネントの定性動作<font color="#008080">[＊＊＊は-を-する]</font></td> </tr> </table> <p style="margin:1 10; line-height: 150%; "> 　</p> <p style="margin:1 10; line-height: 150%; "> いずれの文書も，段落を「人の行為」と「製品の動作」で構成する点で共通です．この際，それぞれがあいまいに混在すると「述語」が人あるいは事物のいずれを主語にしているかがあいまいになってしまいます．とりわけ，プログラマ開発者向け仕様書では，人が主語とも事物が主語ともとれる述語（例：実装）を用いる場合があります．「主語を省略せず能動文で表す」を原則とするとともに，述語に用いる動詞・助動詞を選別する必要があります．</p> <ul> <li> <p style="line-height: 150%; margin-top:0; margin-bottom:15"> <font color="#000080"> たとえば「行う」は，本来は人を主語にして用いるべき動詞です．主語をあいまいにして「-を行う」とすると，「プログラム開発者に指示している」とも「プログラム開発者が意図して行う」さらには「主題になっている事物が定性的に動作を“実行”する」とも二重三重に受けとられるおそれがあります．</font></p> </li> </ul> <HR><p> <a target="_parent" href="tgb-00-99f.htm"> <IMG SRC="../t1/nxt.gif" ALT="" ALIGN=BOTTOM width="37" height="37"></a> <B>次ページに進む</B><FONT COLOR="#008080"><B>（ボタンをクリックしてください）</B></FONT></p> <HR><DIV ALIGN=CENTER><A HREF="../../index.htm" TARGET="_parent"> <IMG SRC="../gif/modoru.gif" ALT="" ALIGN=BOTTOM width="180" height="50"></A></DIV> <HR> <p style="margin-top: 2; margin-bottom: 0; line-height:200%"> <IMG SRC="../gif/sec-teian-b.gif" ALT="実務別技術文書セミナー" ALIGN=BOTTOM width="540" height="26"></p> <TABLE cellspacing="0" cellpadding="0" width="913"> <TR> <TD VALIGN=TOP WIDTH=73> <DIV ALIGN=CENTER></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5><BR> </TD> <TD VALIGN=TOP WIDTH=835> <DIV STYLE="line-height:1.5;margin-top:5px;margin-right:5px;margin-bottom:5px;margin-left:5px;"><FONT COLOR="#000080"><B>実務別技術文書セミナー</B></FONT>（出張開催形式）<SPAN STYLE="padding-top:5px;padding-right:5px;padding-bottom:5px;padding-left:5px;">「</SPAN><FONT COLOR="#800000"><B><SPAN STYLE="padding-top:5px;padding-right:5px;padding-bottom:5px;padding-left:5px;">わかりやすい技術文書の作成手法</SPAN></B></FONT>」は，業務で作成する機会の多い文書に応じた「<B>コース選択式</B>」です．各コースごとに必要な考え方・手法・ポイントを事例中心で解説します．</DIV> </TD> </TR><TR> <TD VALIGN=TOP WIDTH=73> <DIV STYLE="font-size:1px"></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5> <DIV STYLE="font-size:2pt"></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=727> <DIV STYLE="font-size:2pt">.</DIV> </TD> </TR><TR> <TD VALIGN=TOP WIDTH=73> <DIV ALIGN=CENTER></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5><BR> </TD> <TD VALIGN=TOP WIDTH=727> <DIV ALIGN=LEFT> <TABLE> <TR> <TD> <IMG SRC="../gif/tw6-sub6gb-ss.gif" ALT="わかりやすい技術文書の作成手法" ALIGN=BOTTOM width="400" height="75"></TD> <TD><BR> </TD> </TR> </TABLE> </DIV> </TD> </TR><TR> <TD VALIGN=TOP WIDTH=73> <DIV ALIGN=CENTER></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5><BR> </TD> <TD VALIGN=TOP WIDTH=727> <DIV ALIGN=LEFT> <TABLE> <TR> <TD> <IMG SRC="../gif/tw6-sub6mnl-s4-b.gif" ALT="わかりやすい技術文書の作成手法＜製品解説・技術解説編＞" ALIGN=MIDDLE VSPACE=10 width="400" height="36"></TD> <TD><A HREF="../t6b/gb-smnr-b.htm" TARGET="_parent"> <IMG SRC="../gif/lnk-htmlsg.gif" ALIGN=bottom width="95" height="36"></A></TD> <TD><A HREF="../t6b-pdf/gaiyo-gb02b.pdf" TARGET="_parent"> <IMG SRC="../gif/lnk-pdf2s.gif" ALT="" ALIGN=BOTTOM width="210" height="36"></A></TD> </TR> </TABLE> </DIV> </TD> </TR><TR> <TD VALIGN=TOP WIDTH=73> <DIV ALIGN=CENTER></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5><BR> </TD> <TD VALIGN=TOP WIDTH=727> <DIV ALIGN=LEFT> <TABLE> <TR> <TD> <IMG SRC="../gif/tw6-sub6mnl-s4-c.gif" ALT="わかりやすい技術文書の作成手法＜報告文書＋解説文書編＞" ALIGN=MIDDLE VSPACE=10 width="400" height="36"></TD> <TD><A HREF="../t6c/gb-smnr-c.htm" TARGET="_parent"> <IMG SRC="../gif/lnk-htmlsg.gif" ALIGN=bottom width="95" height="36"></A></TD> <TD><A HREF="../t6c-pdf/gaiyo-gb02c.pdf" TARGET="_parent"> <IMG SRC="../gif/lnk-pdf2s.gif" ALT="" ALIGN=BOTTOM width="210" height="36"></A></TD> </TR> </TABLE> </DIV> </TD> </TR><TR> <TD VALIGN=TOP WIDTH=73> <DIV ALIGN=CENTER></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5><BR> </TD> <TD VALIGN=TOP WIDTH=727> <DIV ALIGN=LEFT> <TABLE> <TR> <TD> <IMG SRC="../gif/tw6-sub6mnl-s4-e.gif" ALT="わかりやすい技術文書の作成手法＜機能仕様書＋製品解説編＞" ALIGN=MIDDLE VSPACE=10 width="400" height="36"></TD> <TD><A HREF="../t6e/gb-smnr-t6e.htm" TARGET="_parent"> <IMG SRC="../gif/lnk-htmlsg.gif" ALT="" ALIGN=BOTTOM width="95" height="36"></A></TD> <TD><A HREF="../t6e-pdf/gaiyo-gb01e.pdf" TARGET="_parent"> <IMG SRC="../gif/lnk-pdf2sg.gif" ALT="" ALIGN=BOTTOM width="210" height="36"></A></TD> </TR> </TABLE> </DIV> </TD> </TR><TR> <TD VALIGN=TOP WIDTH=73> <DIV ALIGN=CENTER></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5><BR> </TD> <TD VALIGN=TOP WIDTH=727> <DIV ALIGN=LEFT> <TABLE> <TR> <TD> <IMG SRC="../gif/tw6-sub6mnl-ss-d.gif" ALT="わかりやすい技術文書の作成手法＜製品解説＋技術メール編＞" ALIGN=MIDDLE VSPACE=10 width="400" height="36"></TD> <TD><A HREF="../t6d/gb-smnr-d.htm" TARGET="_parent"> <IMG SRC="../gif/lnk-htmlsg.gif" ALT="" ALIGN=BOTTOM width="95" height="36"></A></TD> <TD><A HREF="../t6d-pdf/gaiyo-gb01d.pdf" TARGET="_parent"> <IMG SRC="../gif/lnk-pdf2sg.gif" ALT="" ALIGN=BOTTOM width="210" height="36"></A></TD> </TR> </TABLE> </DIV> </TD> </TR><TR> <TD VALIGN=TOP WIDTH=73> <DIV STYLE="font-size:2pt"></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5> <DIV STYLE="font-size:2pt"></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=727> <DIV STYLE="font-size:2pt">.</DIV> </TD> </TR><TR> <TD VALIGN=TOP WIDTH=73> <DIV STYLE="font-size:2pt"></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=5> <DIV STYLE="font-size:2pt"></DIV> </TD> <TD VALIGN=TOP BGCOLOR="#0080c0" WIDTH=727> <DIV STYLE="font-size:2pt">.</DIV> </TD> </TR> </TABLE> <DL> <DT>　</DL> <HR> <p> <B>テクニカルドキュメント・ビジネスドキュメントためのテクニカルライティングセミナー</B><BR> <B>わかりやすい技術文書・ビジネス文書の作成手法</B><BR> <B>技術文書の「書き方」－共通のポイントと各種文書への応用－<br> </B>Copyright:Takaaki-YAMANOUCHI/1995-2010<BR> 山之内孝明／(有)山之内総合研究所<BR> Takaaki Yamanouchi/ Yamanouchi Research Institute,Ltd.</p> </BODY>