「ソフトウェアドキュメンテーション」塩谷敦子、菊池百代, デンソークリエイト, 1999, ISBN4-931392-04-4 第二版, 2000
を拝見している。
11個の良いいことが書いてある。それぞれのよいことの理解、事例を付記してみる。
###1 設計
・解説書からの脱却
source codeは設計です。論理回路言語のVerilogHDLなどでは、ソースコードが設計で、回路図が実装です。計算機言語でもソースコードが設計で、機械語が実装です。１対１対応しているわけではないことに注意してください。compile option, link optionで様々な機械語に実装可能です。
source codeの注釈(comment)が、関数の日本語訳になっていたり、解説になっていて、source codeを治す度に、 注釈も直さなくてはいけないのは、できるだけ避けたい。
###2
・ドキュメントの構造化
複数のライブラリ(source code付き、なしのどちらの場合も）を利用する場合に、両方の構造を分析し、どう組み合わせるとよいかを検討するとよい。
source code付きの場合に、手を入れる（入れてもらう）かどうかも、構造化の方針による。
覆(rapper)を作るだけにするか、命名規則をどうするか、構造化の方針によって違うかも。
###3
・文章の構造化
構造化したsource codeには、設計図以外には、仕様書、設計書など他の文書があまり必要ないというのが経験則。
COBOLのように、仕様の一部である環境を記述する習慣が、他の言語では規定でないのは残念。
他の言語の良いところは見習い、ソースコードの最初に仕様と環境等の制約条件を、その次に設計の基本的な構造と必要な図へのURL等を書くとよい。
p.9
###4
・目次を決めること = 仕様・設計の項目を決め、全体像を明らかにすること
source codeに仕様・設計の項目の記述をし、全体像を明らかにするとよい。
場合によっては、仕様記述言語、設計記述言語（プログラミング言語）で書くとよい。
仕様、設計は自然言語の記述をなくすとよい。
図等のXMLファイルをソースコードに注釈としてつけても良い。
###5
・タイトルと内容の一致
関数名と処理の内容が違ったら、名前の意味がない。
関数機能を機密にし、source codeを公開しない場合はこの限りではない。
関数名は標題(title)であり、機密上の理由がないかぎり、処理の中身を意味する言葉にする。
関数機能は、試験プログラムによって、その機能を類推できる可能性がある。
隠せば、覗きたくなるといういたちごっこをするより、open sourceにするのも一つの手かも。
###6
・目的や意味をあきらかにすること＝優れた開発用ドキュメントの条件
関数名の前後に書く注釈は、開発目的・意味と連動した、関数の目的・意味のうち、関数名では表現しきれていないことを記述するとよい。
p.10
###7
・記述視点の統一
設計(source code)の記述視点は、入力、処理、出力、操作者、保守者など、いくつか考えられる。
操作者も、子供、高齢者、障碍者など、いくつもの視点が必要である。
それらを体系的に整理することが統一(integlation)であって、視点を一つにすることが統一ではない。
###8
・用語の整理と定義
自然言語には、正しいという概念を適用すると矛盾だらけになり立ち往生する。
正しいという概念が必要な場合は、論理仕様記述言語で記述するとよい。
用語は言語仕様で定義している。
無駄な用語を使わずに、無駄な定義を少なくすることが、体系を単純にし、破綻を防ぐ可能性がある。
利害関係者の間では、用語が逆転していることもしばしばである。
関係者の間の用語の整理と定義の矛盾を確認するとよい。
p11
###9
・ 図の意味の明示
状態遷移図(state chart)、時系列図(sequence chart)、刻時図(timing chart)、利用事例図(use case chart)などの図や、目標構造記述(GSN: Goal Structuring Notation)などと、Source Code上の用語の違いなどで誤解が生じないようにするとよい。
###10
・ 改定履歴
Github, Gitlab, Bitbucketなどのgit系を利用していれば、改定履歴の保存は容易である。
一貫性の確認も、元に戻すことができるのであるから、プログラミングするのはむづかしくない。
Github, Gitlab, Bitbucketのシステムのwikiの機能も改定履歴機能があり、元に戻すことができる。
課題は、改定者の意図が分かるようにする工夫である。
小さな事業では、記号、略号でも改定者の意図はわかるかもしれない。
大きな事業では、いろいろな立場の人が関わると、改定者の意図が伝わらないかもしれない。
###11
・表記法の工夫
改定履歴で記載したように、表記法の工夫で解決する課題と、仕様記述言語、表記言語など複数の言語を採用することによって解決する課題とがあるかもしれない。
表記法上の工夫は、手で行わずに、道具にするとよい。
安全工学シンポジウム2019
安全分析の図的表現方法、及び設計文書と親和性の高いツールの提案
ガイオ・テクノロジー（株）技術開発本部 技術戦略室 技術戦略グループ 田中伸明, 名古屋市工業研究所 小川清
https://www.gaio.co.jp/newslist/anzen_org2019/
#課題・経験則
###ドキュメンテーション
「文書化」または「文書」ではなぜ駄目なんでしょう。
文書の評価の一つに、重要な言葉の占める単語と文字数の関係についての議論があります。
経験則１ 頻出する重要語は、なるべく短く
検討の対象として「ソフトウェア」と「ドキュメンテーション」がある。
ソフトウェアは、軟件と書くと怒る人がいるし、算譜と書くと、異論を唱える人がいて、やっかい。
ドキュメンテーションは、文書化か文書でいい。
なぜ、カタカナ語を使い、不必要に文字数を増やすのかが疑問。
###経験則２ カタカナ語はその分野の専門用語だけに限定し、他の分野の用語では用いない。
#仕様書、設計書
p.4
ソフトウェアの開発は、仕様書や設計書を作成することを中心に進めていくべきです。
明らかにおかしい。少し手直ししてみる。
ソフトウェアの開発は、仕様や設計を中心に進めていくべきです。
市場・顧客視点が抜けている。システムの制約も抜けている。
ソフトウェアの開発は、システムの制約と市場・顧客の動向にもとづいた仕様や設計を中心に進めていくべきです。
分業すると、仕様書や、設計書を埋めることが仕事だと思い、市場、顧客、システム制約に焦点を絞らない可能性があります。
###経験則3 三方よし、三つ以上の立場で見直す。
#開発工程
落水模型(water fall model)にもとづいて、それぞれの工程に文書を作っても、
実際は、20年くらい前から機敏(agile)が主流だったと感じている。
無駄な工程、無駄な文書を減らす工夫をまず語るのがよい。
経験則4 良くすることを考える前に、減らすことを考えてみる
1.3 開発用ドキュメンテーションの指針
いいことをいっぱい書いている。開発指針（source codeを含む）であるとなおよい。
ドキュメンテーションという言葉はいらない。
すべてdocumentなのだから。allを省略するのは論理的かも。
経験則5 相似な構造を探す
#参考資料(reference)
「外来語」言い換え提案
https://www2.ninjal.ac.jp/gairaigo/
##参考資料 on Qiita
まぎらわしい、間違えやすい、行き違いの多い略号worst 10(候補24)
https://qiita.com/kaizen_nagoya/items/0bff5dbb72208053489b
仮説・検証(88)用語の衝突(用語・用例募集中)
https://qiita.com/kaizen_nagoya/items/6a8eb7ffaa45eeb16624
プログラマが知っているとよい英単語の語源
https://qiita.com/kaizen_nagoya/items/9de6d47c47e2c211222b
プログラマが心がけるとよい文章の書き方
https://qiita.com/kaizen_nagoya/items/af1e6207ccaa063dafb8
「ソフトウェア品質シンポジウムでBest Paper Effective Awardを受賞するコツ？」に付け加えたい5つのこと
https://qiita.com/kaizen_nagoya/items/70a53f19d95d571a0e48
#文書履歴(document history)
ver. 0.01 初稿 20190724
ver. 0.02 安全分析の図的表現方法 20190425 朝
ver. 0.03 参考文献 20190425 午前
ver. 0.04 参考文献 20210117
ver. 0.05 標題「塩谷敦子、菊池百代」追記 20211008
最後までおよみいただきありがとうございました。
いいね 💚、フォローをお願いします。
Thank you very much for reading to the last sentence.
Please press the like icon 💚 and follow me for your happy life.
