「ソフトウェアドキュメンテーション」塩谷敦子、菊池百代, デンソークリエイト, 1999, ISBN4-931392-04-4 第二版, 2000
を拝見している。
https://bookmeter.com/books/7984303

11個の良いいことが書いてある。それぞれのよいことの理解、事例を付記してみる。

1　設計

・解説書からの脱却

source codeは設計です。論理回路言語のVerilogHDLなどでは、ソースコードが設計で、回路図が実装です。計算機言語でもソースコードが設計で、機械語が実装です。１対１対応しているわけではないことに注意してください。compile option, link optionで様々な機械語に実装可能です。
source codeの注釈(comment)が、関数の日本語訳になっていたり、解説になっていて、source codeを治す度に、注釈も直さなくてはいけないのは、できるだけ避けたい。

設計は図で書いても、プログラミング言語のソースコードで書いてもよい。

図を使って分析・設計すればこんなに簡単。安全(11), 図(11) https://qiita.com/kaizen_nagoya/items/6347eb55b2812d745549

設計図(12) 表はいつ(when)書く、何を(what)書く、どうやって(how)書く。仮説(71) https://qiita.com/kaizen_nagoya/items/7fddfa5d8bfb5a947db8

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

関連資料

' @kazuo_reve 私が効果を確認した「小川メソッド」
https://qiita.com/kazuo_reve/items/a3ea1d9171deeccc04da

' @kazuo_reve 新人の方によく展開している有益な情報
https://qiita.com/kazuo_reve/items/d1a3f0ee48e24bba38f1

' @kazuo_reve Vモデルについて勘違いしていたと思ったこと
https://qiita.com/kazuo_reve/items/46fddb094563bd9b2e1e

自己記事一覧

プログラマが知っていると良い「公序良俗」
https://qiita.com/kaizen_nagoya/items/9fe7c0dfac2fbd77a945

逆も真：社会人が最初に確かめるとよいこと。OSEK(69)、Ethernet(59)
https://qiita.com/kaizen_nagoya/items/39afe4a728a31b903ddc

「何を」よりも「誰を」。１０年後のために今見習いたい人たち
https://qiita.com/kaizen_nagoya/items/8045978b16eb49d572b2

Qiitaの記事に３段階または５段階で到達するための方法
https://qiita.com/kaizen_nagoya/items/6e9298296852325adc5e

物理記事　上位100
https://qiita.com/kaizen_nagoya/items/66e90fe31fbe3facc6ff

量子(0) 計算機, 量子力学
https://qiita.com/kaizen_nagoya/items/1cd954cb0eed92879fd4

数学関連記事１００
https://qiita.com/kaizen_nagoya/items/d8dadb49a6397e854c6d

統計(0)一覧
https://qiita.com/kaizen_nagoya/items/80d3b221807e53e88aba

図(0) state, sequence and timing. UML and お絵描き
https://qiita.com/kaizen_nagoya/items/60440a882146aeee9e8f

品質一覧
https://qiita.com/kaizen_nagoya/items/2b99b8e9db6d94b2e971

言語・文学記事　１００
https://qiita.com/kaizen_nagoya/items/42d58d5ef7fb53c407d6

医工連携関連記事一覧
https://qiita.com/kaizen_nagoya/items/6ab51c12ba51bc260a82

自動車　記事　１００
https://qiita.com/kaizen_nagoya/items/f7f0b9ab36569ad409c5

通信記事１００
https://qiita.com/kaizen_nagoya/items/1d67de5e1cd207b05ef7

日本語（０）一欄
https://qiita.com/kaizen_nagoya/items/7498dcfa3a9ba7fd1e68

英語(0) 一覧
https://qiita.com/kaizen_nagoya/items/680e3f5cbf9430486c7d

転職(0)一覧
https://qiita.com/kaizen_nagoya/items/f77520d378d33451d6fe

仮説（0）一覧（目標100現在40）
https://qiita.com/kaizen_nagoya/items/f000506fe1837b3590df

音楽　一覧(0)
https://qiita.com/kaizen_nagoya/items/b6e5f42bbfe3bbe40f5d

「@kazuo_reve 新人の方によく展開している有益な情報」確認一覧
https://qiita.com/kaizen_nagoya/items/b9380888d1e5a042646b

Qiita(0)Qiita関連記事一覧（自分）
https://qiita.com/kaizen_nagoya/items/58db5fbf036b28e9dfa6

鉄道（０）鉄道のシステム考察はてっちゃんがてつだってくれる
https://qiita.com/kaizen_nagoya/items/26bda595f341a27901a0

安全（0）安全工学シンポジウムに向けて: 21
https://qiita.com/kaizen_nagoya/items/c5d78f3def8195cb2409

一覧の一覧( The directory of directories of mine.) Qiita(100)
https://qiita.com/kaizen_nagoya/items/7eb0e006543886138f39

Ethernet 記事一覧　Ethernet(0)
https://qiita.com/kaizen_nagoya/items/88d35e99f74aefc98794

Wireshark 一覧 wireshark(0)、Ethernet(48)
https://qiita.com/kaizen_nagoya/items/fbed841f61875c4731d0

線網（Wi-Fi）空中線(antenna)(0) 記事一覧(118/300目標)
https://qiita.com/kaizen_nagoya/items/5e5464ac2b24bd4cd001

OSEK OS設計の基礎　OSEK(100)
https://qiita.com/kaizen_nagoya/items/7528a22a14242d2d58a3

Error一覧 error(0)
https://qiita.com/kaizen_nagoya/items/48b6cbc8d68eae2c42b8

++ Support(0)　
https://qiita.com/kaizen_nagoya/items/8720d26f762369a80514

Coding(0) Rules, C, Secure, MISRA and so on
https://qiita.com/kaizen_nagoya/items/400725644a8a0e90fbb0

coding (101) 一覧を作成し始めた。omake:最近のQiitaで表示しない5つの事象
https://qiita.com/kaizen_nagoya/items/20667f09f19598aedb68

プログラマによる、プログラマのための、統計(0)と確率のプログラミングとその後
https://qiita.com/kaizen_nagoya/items/6e9897eb641268766909

なぜdockerで機械学習するか書籍・ソース一覧作成中 (目標100)
https://qiita.com/kaizen_nagoya/items/ddd12477544bf5ba85e2

言語処理100本ノックをdockerで。python覚えるのに最適。:10+12
https://qiita.com/kaizen_nagoya/items/7e7eb7c543e0c18438c4

プログラムちょい替え（0）一覧:4件
https://qiita.com/kaizen_nagoya/items/296d87ef4bfd516bc394

Python(0)記事をまとめたい。
https://qiita.com/kaizen_nagoya/items/088c57d70ab6904ebb53

官公庁・学校・公的団体（NPOを含む）システムの課題、官（０）
https://qiita.com/kaizen_nagoya/items/04ee6eaf7ec13d3af4c3

「はじめての」シリーズ　ベクタージャパン　
https://qiita.com/kaizen_nagoya/items/2e41634f6e21a3cf74eb

AUTOSAR(0)Qiita記事一覧, OSEK(75)
https://qiita.com/kaizen_nagoya/items/89c07961b59a8754c869

プログラマが知っていると良い「公序良俗」
https://qiita.com/kaizen_nagoya/items/9fe7c0dfac2fbd77a945

LaTeX(0) 一覧　
https://qiita.com/kaizen_nagoya/items/e3f7dafacab58c499792

自動制御、制御工学一覧（０）
https://qiita.com/kaizen_nagoya/items/7767a4e19a6ae1479e6b

Rust(0) 一覧　
https://qiita.com/kaizen_nagoya/items/5e8bb080ba6ca0281927

100以上いいねをいただいた記事16選
https://qiita.com/kaizen_nagoya/items/f8d958d9084ffbd15d2a

小川清最終講義、最終講義（再）計画, Ethernet(100) 英語(100) 安全(100)
https://qiita.com/kaizen_nagoya/items/e2df642e3951e35e6a53

＜この記事は個人の過去の経験に基づく個人の感想です。現在所属する組織、業務とは関係がありません。＞
This article is an individual impression based on my individual experience. It has nothing to do with the organization or business to which I currently belong.

文書履歴(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.

https://b.hatena.ne.jp/guide/bbutton