補足：　　チュートリアルとパネルディスカッションで使用したスライドは、　　ASDoQ Webのトピックスページから、ダウンロードできます。　　スライドを参照しながら、議事録を読まれると、理解が進みます。　　　　ASDoQトピックスページは、こちら⇒　http://asdoq.jp/news/ ********************************************************************** セッションS45-d 誰がために開発文書を書くテーマ：新しい開発文書の時代を迎えて講師：山本雅基氏（名古屋大学）コーディネータ：栗田　太郎　氏（フェリカネットワークス株式会社）日時：2011/9/2 13:00〜13:50 参加人数：約40名（終了時） ********************************************************************** 今年７月に新たに発足したシステム開発文書品質研究会(ASDoQ) のメンバーが中心になってこのセッションを企画した。対象は若い開発者。笑顔があふれる、ためになるチュートリアル。・自己紹介　アロハの西先生の向こうを張り、作務衣を着ている。　帽子を被っている理由は後で。・開発文書　ソフトウェアの開発過程でドキュメント化（自然言語、UMLなど）されたもの。　ソースコードも開発文書と言える？・誰がために開発文書を書く　５択のアンケートを行った。回答は二つまで、一つでもよい。　１番：顧客のため　　　　　　７人　２番：後工程の開発者のため　２３人　３番：品質保証部のため　　　２人　４番：私のため　　　　　　　１６人　５番：書かない　　　　　　　１人　２，４番が動機として多い。・誰がために鐘は鳴る(ヘミングウェイ) 　ヘミングウェイの小説からのオマージュでセッションの題名をつけた。　映画「誰がために鐘は鳴る」で，主役のゲーリー・クーパーが帽子をかぶっているため、山本先生も帽子をかぶっていた。・開発文書とは　ASDoQの研究会では開発文書について議論、研究を行っている。　山本先生もASDoQの研究会に所属している。　開発文書は開発の過程で作成される。　アクティビティの入出力として規定された文書として定義できる。　議事録なども開発文書ではないかと質問されたことがある。　どこまで開発文書と言えるのかは面白いテーマ。・開発文書とはアクティビティーの入出力である　システムアーキテクチャ設計書、ソフトウェア要求分析書は開発文書と言える。　ソフトウェア技術者の仕事の成果が開発文書。・顧客のために書かされる開発文書　現在のソフトウェア開発では説明責任やソフトウェア品質の判断のため、　お客さんにソースコード、テスト報告書、設計書を納入することが多い。　昔はお客さんにソースを渡さないことが多かった。　納入のために開発文書を書くのもモチベーションになるが　開発文書はそれだけのためのものでない。・後工程の開発者のために書かされる開発文書　人のために仕事をするのは、美しい。　・品質保証のため書かされる開発文書　品質保証会議で通すために開発文書を書くことがある。　業種によっては鬼のようなルールが存在し、頑張って仕事をする必要がある。　品質保証部のような強い権限を持った部には敵対心も持ちがちだが、　誤っている。　品質保証のために、建設的な議論が必要。・プロセスと品質はデミングから　戦争が終わってからアメリカからデミングが来日した。　日本はデミングの指導を実践して、品質が劇的によくなった。　デミングは、その業績で日本で勲章をもらった。後年、アメリカでも評価された。・デミングの主張　品質を開発プロセスで制御することを主張した。　他方、テイラーは製品制御方式で品質を保証しようとしたが、　複雑なシステムでは成功しないので、ソフトウエア開発には不向き。・開発文書で開発プロセスを制御　デミングは、統計的にプロセスを制御した。　ソフトウェアは一本ものなので、統計情報がなく適用できないように思える。　しかし、プロセスを制御するという、デミングが主張するフレームは適用可能。　ソフトウェア開発プロセスの制御のために、開発文書が利用できる。・「書かされている感」からの卒業　顧客、後工程開発者、品質保証部のために開発文書を書くことは正しいが、　開発文書を書かされていると感じる。　開発文書には他に本質的な目的があり、それに気づけば、書かされているから　卒業でき、　能動的に開発文書を書くようになる。・私のために書く開発文書　若い人には怒られたくないために開発文書を書いている人多数。　もし私に娘がいたら、そんな奴に、娘を嫁にやらん。　他によくいるのが何も考えないで開発文書を書く人。　それも、志が低い。・なぜ、志が低くなるのか？　みな自分を作業者と考えているため志が低くなる。　作業と仕事は違う。　自分で考えてマニュアルを超えた仕事するのがプロフェッショナル。・技術者のあなたが生む付加価値は　入力文書と出力文書の差分が、あなたが生んだ付加価値。　前のと同じ文書を出している場合は仕事の価値がない。　付加価値を生み出すことが仕事である。・技術者になるために書こう　技術者ならば、付加価値を生み出せ。付加価値はみえる必要がある。　自分で自分の仕事の確認や他者に見えるように開発文書を書くべきである。　見えると成長ができる。　書かされるのではなく、率先して書いて付加価値を生み出せ。　開発文書を書かない人だってプログラムを能動的に書いている。　プログラムはCPUが読めるもの。　コンピュータが読むプログラムを書けるならば、人が読む要求仕様書だって書けるはず。　何を書けばいいか分からないから教えてくれと言っている限り、技術者として大成しない。　自分で工夫していかない限り、成長しない。・あなたはすでに能動的に書いている　技術者ならば、書こう。　技術者になるために、書こう。　技術者として生きている証を残すため開発文書を書こう。・開発文書の問題はさらにに続く　何を書けばよいのか？　どのように書けばよいのか？　どうやって技術者を教育すればよいか？　　開発文書と品質とは？　この辺りの話はASDoQの会員になってやってほしい。 ○質疑応答　資料への直接的な質問のみ受け付けたが、なし ********************************************************************** セッションS45-d 誰がために開発文書を書くテーマ：開発文書と私コーディネータ：栗田　太郎　氏（フェリカネットワークス株式会社）パネラ　　　　：坂本　佳史　氏（日本IBM株式会社）　　　　　　　　塩谷　敦子　氏（合同会社イオタクラフト）　　　　　　　　清水　吉男　氏（株式会社システムクリエイツ）　　　　　　　　杉本　明加　氏（富士設備工業株式会社）　　　　　　　　藤田　悠　　氏（長野工業専門学校）　　　　　　　　山本　雅基　氏（名古屋大学）　　　　　　　　森川　聡久　氏（株式会社ヴィッツ）日時：2011/9/2 14:00〜15:50 参加人数：約40名（終了時） ********************************************************************** ○自己紹介最初にコーディネータと各パネラの自己紹介を行った。各パネラは同時に「私にとっての開発文書」を発表した。 ●コーディネータ：栗田氏　業務としてプリカの開発、ソニーの仕様記述言語の開発等を行った。 ●坂本氏　サービス関係の仕事をしていて、現在プロジェクトマネージャーをしている。　もともと半導体屋であった。・私にとっての開発文書：　製品開発プロジェクトにおける最も重要なコミュニケーション手段の１つで、　文書がないことには難しいことも多い。　しかし、技術者は開発文書を作ることを好き好んでやらない。　文書化は真っ先にはじかれるけれどそれでいいのか？と感じている。 ●塩谷氏　開発文書の改善活動をしている。　最初は自動車業界の研究所で働いていて開発文書とは関係ない仕事をしていた。　研究に向いてないかと思って開発の仕事をして　自動車メーカーのソフト会社に就職した。　その後、開発より教育をやりたいと思った。　会社内に限らず企業向けの教育も行っている。・私にとっての開発文書：　以前は、仕様書など見たことなく議事録とかを仕様書代わりに使っていた。　開発文書の大切さを広めたいと考えていて、CQ出版の雑誌で６回コラムを書いた。　研究所時代に、出張報告とか何度も書き直させられた徹底的に赤ペンで　直されたのが開発文書の教育に役立った。　私にとっての開発文書は教育と直接のアドバイスをするためのもの。 ●清水氏　４０年間フリーとして仕事をしてきた。　開発文書を組織で書かされたことないはないため、納品のため書いていた。　後で見てしっかり書いているな〜と思われる開発文書を書きたいと考えていた。　先輩に教えられたことはないため、自分で考えなきゃいけないというのが　身に付いた。・私にとって開発文書：　最後に設計したのが９５年のためよく覚えてない。　最初の３年間は要求仕様書で破綻して事業を撤退した。　復帰後、仕様漏れのない要求仕様書の書き方を勉強しなおして自分で習得した。　７２，３年あたりから納期遅れ仕様トラブルはなかった。 ●杉本氏　以前はT社系列で計算機の組み込みアプリ開発に従事していた。　今は富士設備工業株式会社でツールサポートにしている。　個人としてTOPPERS/ASPプロジェクトに参画している。　最小セットカーネルなどを仕事の傍らやっているが趣味でやっている部分もあり　楽しくやっている。・私にとっての開発文書：　昔は大嫌いであった。動けばよいやと思っていた　今は思考過程を表現するものと考えている。　実現したいことをソースに落とすのだけどいきなりソースで書くことはありえない。　開発文書を書くと結果的に良いソースとなる。　開発文書は大切な成果物。　TOPPERS/ASPはオープンソースのプロジェクトなので誰が開発文書を　使うかわからない。ドキュメントがないときちんと使ってもらえないので　ドキュメントは非常に重要　だんだん経験を積むに従って、いい物を作るためには開発文書が必要と感じている。 ●藤田氏　２００９年から長野高専で活動をしている。　組込みのソフトウェア開発文書に潜んでいる問題の　「診察」「診断」「治療」「予防」をする文書診断法の体系化を行っている。　企業の技術者対象の文書診断法の研修を行っている。・私にとっての開発文書：　書き手の考えがつまびらかになるもの。　正解は一つでないと考えているので赤ペンを入れられても問題ない。　それを受け止めて推敲を繰り返すこと大切と考えている。 ●森川氏　株式会社ヴィッツで機能安全開発や車載用プラットフォーム開発を行っている。　他にも機能安全対応の支援をしている。　機能安全がなぜ求められるのか？　１．安全なシステムを開発するため　　従来は不具合なければOKだったが、機能に故障への対策を求められるようになった。　２．安全性の説明が必要　　第３者検証、妥当性確認を行えるエビデンスを残すのが必要。　３．非関税障壁への対応　　機能安全対応しないと海外へ輸出できない可能性。・私にとっての開発文書：　機能安全の観点から述べる。　開発文書により安全性の確認ができるはず。　文書品質でいえば完全性、可読性、再現性を満たせば安全性を説明できる。　しかし、課題もいろいろある。　規格には明確な基準がなく、どれくらいやればよいか分からない。　経験からいえば肝の理解とそれを満たす対策が重要。　評価の仕方として自社で基準を決めるのもあり。　このスキルを持って作ればこのくらい安全だよねとして運用するのもあり。　会社によって作り方に違いがあり、品質といってもここだというのが難しい。　自社で決めるときは会社に合わせて評価基準を決めればよい。 ●山本氏　名古屋大学で組込み技術者に対する教育手法の研究している。　チュートリアルセッションで発表をしているため自己紹介を略した。 ○本題の発表以下の項目の発表を各パネラが行った。・開発文書にまつわる思い出・問題のある文書・よい文書と工夫・まとめ発表後、質疑応答を受け付けた。 ●藤田氏「文書診断の現場から(1/2).設計行為のための文書の記述」・開発文書にまつわる思い出：　ドキュメントを書かない人が多数のため思い出はない。　誰も読まず、誰にも使われていないから開発文書を書かない。　ドキュメントを読まない理由はソースコードを直接読んだほうが良いため。・問題のある文書：　ある事例で、赤ペン入れて診断したら２０行に２３件問題個所があった。　細かいものもあり、それを見ると直せばよいのかと考えてしまう。　中身をよく考えてほしいと考えている。　起動条件と題名に書いてあるのに起動条件がいっぱいでる。・良い文書と工夫：　１．表や箇条書きで整理されている。　　例として起動条件と非起動条件と分けてある。　２．段落の構成を画期表したもの　　流れを平たく書いたほうが分かりやすい。　３．図を用いて分析を行ったもの　　図を用いて箇条書きで整頓。　文書としてよいかは別。・まとめ　超人能力が無いならば文書を使って推敲や設計しよう　文書診断によって洗い出された問題に対処する取り組みは深く考えることにつながる。　文書の品質を高める為、客観的な視点からの意見を積極的に取り組みましょう・質疑応答　Q.文書を書くのは推敲や設計のため？　A.私はそう考える。　Q.文書の品質を高めるというが、品質とは何か？　A.書く人が伝えたいことが読み手に伝わること。　Q.ソースコードに表や箇条書きの情報を書くのもありでは？　　だからソースコードも文書では？　　制御構造が見えれば良いのでは？　　いきなりソースコードを書くのが悪いのは制御が見えないから？　A.ソースを文書と見るのは定義だから好きにすれば良い。　　具体的な情報をプログラムに書くのもあり。　　違う抽象度なら分けて書くのもあり。　　どういう抽象度かによると思う。　　省かれることは悪くて記憶に残らない、　　残らないのが悪いならソースに書いて妥協するのもあり。　　思考過程があることも大事。　　作っている人が自分のために書いた場合はどこに何があるか他者から分からない。　　他者が見る場合はソースコード中に書くと探せない。　　どこに何があるか分からないから使い分けてほしい。　Q.設計仕様？要求仕様？　A.あいのこ。　　はっきりしないことがが問題かなって思う。　　目的が決まっていないことが問題。・参考文献　学生のためのテクニカルライティング　基礎日本語辞典　文章ドクター　新版　悪文　文章の問題は基本的に変わっていないと考えている。　気づきによって解決する手法しかないかな？と感じている。 ●塩谷氏「文書診断の現場から(2/2).開発文書の心得１０箇条」・開発文書にかかわる思い出「赤ペン先生が赤ひげ先生になるとき」　開発文書を専門外の立場から見ていて、開発文書としてどこが悪いかを見ている。　専門家ではないので設計レビューはしていないが、　設計として詰めておくべき設計として論理的でない箇所が見つかることも度々ある。　例１）「水漏れ検出プログラム要求定義書」の目次　文書は何を目的としているかを見るためにまず目次をチェックする。　目的がなっていないとき赤線を引く。　要求定義書に処理方法が書いてあったりするのは良くない。　例２）あるソフトウェア設計書の記述　センサが出てくる　電流値などはソフトのデータとして必要だが、ソフトはセンサを扱わない。　全体のシステムとしてとらえるならセンサは必要だが、　そこで必要なデータをきちっと書くことが重要。　システムとソフトでデータの扱いの切り分けが必要。・問題を含む文書　上と下のアクティビティで同じことを書いても意味がない。　同じことを書いてあると、その部分をどこで決めたか分からない。　上位文書と全く同じ図が出てると、下位文書を書いた人が何を設計したかわからない。　これ以降の文書で必要と設計者は主張する場合があるが　そういう場合はそのことを明記する必要がある。　コピーをするだけではなにも設計してない。・良い開発文書と工夫　十箇条があるが一つも説明しない。　興味あれば弊社のセミナーを受けてほしい。　ソフトウェア開発は伝言ゲームではなく、同じことを伝達しても開発でない。・おわりに　書くことを自分の味方にしてほしい。、　あらぬ誤解を受けないよう伝える、自分の作業を伝える為に書くべき。　書くことは考えることで、考えることは書くことに同期しよう。　ソフトウェア開発はドキュメンテーション。・質疑応答　Q.考えることと書くことを同期しようといったけど、できる時とできない時があるのでは？　　はじめてやることはできない？　A.メモ書きも含めて考えてる。　Q.赤ペン先生やるタイミングは？　A.できあがったモノがほとんど、お客に言われたことに従ってやる。　　直して初めて意味がある。　　できれば途中でやりたいが、何回も直すのは開発には無理と感じる。　　質問者は目次をまず書いて目次をレビューする。　　目次をまず書くのは素晴らしい。全体像をまず見るのが重要　Q.十カ条の１条のドキュメント体系で決めると書いてあるが　　ドキュメント体系をどう決める？　A.何を作るかでもってドキュメントで何を作るのか決まる。　　成果物として何を作るかでドキュメント体系を決まる。　　２条の部分を開発作業の構成はドキュメント構造であると　　言い直したほうが良いかもしれない。 ●坂本氏「開発の現場から.それぞれの自然言語処理技術の活用」・開発文書にまつわる思い出　LSIの要求仕様書に　「その他のエラーはすべてハードウェアでハンドリングすること」　と書いてあった。　ハンドリングが特に問題で、この一文で１２時間話し合いになった。　あいまいな文章は大きな問題となる可能性。・問題のある文書　「コンポーネントAは起動通知を受信するまで動作しない」という記述は　起動通知を受信することで動作を開始するか、　起動通知により動作を停止するか一意に判断できない。　自動車関連のソフトなので特に怖い。・良い文書の工夫　良い文書の考え方は藤田さんといっしょで誤解を与えず　正確に情報を伝えられること　工夫にはあいまいさがなく、一意の表現で記述すること、　開発文書に求められる情報を漏れなく記述すること、　正しい文法で簡潔な表現で記述することが挙げられる。・自然言語処理技術と文書品質の確認　オフィスPCでも形態素解析、文型解析可能なソフトウェアが社内にある。　このソフトウェアで文書品質の定量化が可能で、相関をみること出来る。　またトレーサビリティが向上する。　自然言語処理と目視を比較すると0.7以上の強い相関が見れた。　処自然言語理で悪いと判断されたものは人間が見ても悪い傾向が強い。・自然言語処理VS目視　目視はごみがなく、ツールは漏れなし　人間は時間かかるが、ツールはすぐできる。・まとめ　読み手に誤解を与えない文章が重要。　自信ないなら自然言語処理に任せようという流れが来ると思う。・質疑応答　Q.IBMでツールを使われているか？　A.使ってます　Q.使った感想は？　A.社内で自然言語処理ツールを使った感想として、日本語の問題をかなりの確率で発見。　　ここがおかしいと言うだけで、ツールだけでは直せない。　　使用者が見て直す必要がある。　Q.間違いを検出することも重要だが、　　一番大切なのは文章が良くなること。　　ツールからどう直したらいいかとか、　　言われた人が納得するか？　A.できることとできないことの理解が重要。　　なぜおかしいのかをツールが何を見つけるのかを　　事前に理解して、それを教育する必要がある。　Q.どういうツールを使うのか？買える？高い？　A.ここ抜けてますよと簡単に発見できるツール。　　表現の問題はツールで出せる。　　ツールそのものはお求めやすい価格。　　データベースの構築はそれぞれ作らないといけない。　　どの会社に持っていってもどのドメインに持っていってもOKではない。　Q.ドメインで違うといったけど辞書の変更だけでいけないのか？　　文書構造まで変わるのか？　　名詞の長さとか同じ表現でも違う言い方とかなのか？　A.各社各業界で方言の強さはびっくりするほどあるため　　辞書の変更で対応できず、データベースの構築が必要。　Q.技術者しか治せない文章はどのくらいの割合？　A.３割で１割は致命傷。 ●杉本氏「プログラマの視点から」・問題のある文書　中身のない文書は問題がある。　機能安全に携わったがコピーしといてと言われてそれなんだよと思った。　とりあえず書いてみようというのが中小企業でよくある。　仕様書を書く気がないなら書かないほうが良いと思う。・自分にとって良い文書　TOPPERSの開発文書が自分にとって良い文書。　仕様書だけで２００ページくらいあるが漏れがすごく少ない。　一度も間違った記述を見つけたことがない。形がよいかは別としてよい文書。・まとめ　中身がない文書はよくない。　文書を書くことが目的ではだめで、良い文書を書くことが重要。　オープンソースに携わる上でも、文書を書いていこうと思う。　すぐれた文書の例を見るのは良いこと。・質疑応答　なし（残り時間が少なくなり、急いで発表を進めた。） ●森川氏「機能安全と第三者評価」・開発文書にまつわる思い出　「・・など」のような曖昧な表現があると正しい判断ができなくなる　可能性がありリスクが存在する。・問題のある文書　人によって解釈が異なる文書は問題あり。　具体例や明確な図を出すと、文書量が増加するが分かりやすい。　対策ポイントとなるところに文書を追加という書き方も良いと考えている。　別の観点として、機能安全の観点から考えた開発文書はトレーサビリティの管理が必要。　各項目の過不足・矛盾がないことが確認できる必要がある。　変更時のの影響分析にトレーサビリティ管理が必要。　要求事項のトレーサビリティ管理には、要求事項と補足説明を　区別するのがよいが、要求事項と補足説明が分けられないグレーな部分もある。・まとめ　開発文書の品質は様々な観点から重要。　しかし、開発文書の品質は、突き詰めると難しく課題も多い。　開発文書の書き方の決定版を確立していきたい。・質疑応答　Q.機能安全の観点から図の要求はつらいけど　ありなの？なしなの？　A.かけるのであればよい。難しいのかな。　Q.図の良しあしについて、文書の主体は自然言語だが、図は必要か？　A.図は必要。　Q.図をどう評価するか？　A.図は誰にもわかりやすい。　Q.それは疑問。図で書けば誰でも分かりやすいということではない。（議論になるが、時間がなく次へ。） ●清水氏「派生開発とUSDM」・開発文書にまつわる思い出　開発文書の最後の思い出として、時期が重なった２つの新規開発が挙げられる。　初代カラリオの開発と内線電話のデジタル化転送装置の開発を、　まったく違うやり方で新規開発した。　カラリオの開発は構造化分析から構造化設計をシームレスに行った。　構造化手法の良いところは必要以上の言葉が要らないこと。　内線電話のデジタル転送化装置の開発は、顧客側が新規開発のレビューを出来ない　と言ってきたためレビューなしで行った。　レビューされないので、レビューなしでも耐えられるよう　関数のフローチャートを全部ひとつにした。　タスクの文書の構造を同じにしてセルフレビューするしかなかった。　この設計手法で設計ミスなしで開発を行うことができた。・良い文書と工夫　階層表現で仕様を漏れにくくする（USDMの一つの特徴）。　要求仕様と機能仕様を分けてリファインしていく。　仕様は要求に含まれる動詞にあり、要求を上手に書くことで　動詞を見せて仕様を抽出する。・まとめ　仕様が漏れることと読み取りに失敗することは別の問題。　仕様漏れに関してはUSDMで避けれる。　文書が悪ければ仕様漏れが表に出てこない。　仕様漏れというが、度々あるのは要求漏れ。・質疑応答　なし時間が無くなり、これ以降のパネルディスカッションは無し。最後の全体の質問なしこの日の資料はASDoQのホームページに載っている。