大量のドキュメントは本当に必要なのか？無駄だなよ

**デフォルトの名無しさん** · 2021/02/08(月) 03:32:53.15

高品質なソフトほどドキュメントは少ない

Why you need ARCHITECTURE.md
https://www.reddit.com/r/programming/comments/le46br/why_you_need_architecturemd/

**デフォルトの名無しさん** · 2021/02/08(月) 10:15:38.58

実体との齟齬が大きすぎて殆どの場合役に立たない

**デフォルトの名無しさん** · 2021/02/08(月) 12:18:13.80

ソースがドキュメント(mtz)

**デフォルトの名無しさん** · 2021/02/08(月) 13:49:59.63

アプリのドキュメントはともかく、OSのAPIやライブラリの関数や、
classなどのドキュメントはとても重要で、ソースがドキュメントと
いう考え方は絶対駄目。
それをやるから互換性の問題で悩まされ、そのOSやライブラリを使った
アプリが不安定化する。
ソースは一時的なものであって、たまたまそのバージョンのOSや
ライブラリでのみ通用する事情であることが多いから。

**デフォルトの名無しさん** · 2021/02/08(月) 13:58:22.09

もし、安定したOSを目指すなら、むしろソースは非公開にして、ドキュメントで
公開されている仕様のみでアプリを作った方が安定することもある位。
たとえば、fopenやprintf、argv[]やatoi、strtodなどの互換性は、
ソースを見なくてもあらゆるプラットフォームで割と高い。
逆にLinuxのGRUB(ディスクのマルチブートツール)などはLinuxのソースに
基づいてプログラミングされているようで、OSのバージョン間の互換性が低く、
非常に不安定。
しかも、マルチブートしたいだけなのに自分でスクリプト言語を書かなくては
いけない事が多く、僅かでも間違うとディスクの破損事故につながったり、
OSが起動しなくなって簡単には復旧できなくなる可能性がある。
これは、正式なドキュメントによらずにソースの解析に基づいてプログラミング
してしまっていることが要因だと考えられる。

**デフォルトの名無しさん** · 2021/02/13(土) 21:12:43.85

仕様書と設計書の区別がないのか？

**デフォルトの名無しさん** · 2021/02/13(土) 21:17:26.95

>>5
残念ながらLinuxはUNIXの仕様が正確にわからなくて、細かいところはかなり異なるものになった。

C言語もUNIX用に作ったので、仕様が明示されておらず、同じコードでもバラバラで、完全な環境依存になっている。

**デフォルトの名無しさん** · 2021/02/13(土) 21:27:21.74

ドザExcelerの弊害、仕事終わったつもりでいる

**デフォルトの名無しさん** · 2021/02/13(土) 21:54:32.67

コードと一緒で意味あるドキュメントもあるしクソなドキュメントもあるってだけ。
コードと一緒で長くても短くても品質とは関係ない。

**デフォルトの名無しさん** · 2021/02/13(土) 23:42:33.96

品質という言葉で片付けるやつは危険人物

**デフォルトの名無しさん** · 2021/02/13(土) 23:52:02.10

成果物はドキュメントではなく動作するコードです。
コード知らない人の設計書は穴だらけ。

**デフォルトの名無しさん** · 2021/02/13(土) 23:54:03.07

まともなドキュメント書けないSIerみたいなやつはコードもクソだよ。

**デフォルトの名無しさん** · 2021/02/14(日) 00:13:24.81

ドキュメンテーションが苦手で、コーティングが得意なんていうのは、仕事ではありえないんだよな。

**デフォルトの名無しさん** · 2021/02/23(火) 09:16:11.85

得意苦手というよりは、特定のドキュメントが存在することで誰が得するの？って話では？
特定のドキュメントって具体的に何なのかは知らないけど

**デフォルトの名無しさん** · 2021/02/23(火) 15:42:19.69

NECとかに要求される大量のExcelファイルは本当に無駄だと思う

**デフォルトの名無しさん** · 2021/02/23(火) 17:34:52.62

極端に一時的な資料になっているドキュメントも困る。

**デフォルトの名無しさん** · 2021/02/23(火) 17:43:14.11

コードが完成してから書くドキュメントには価値がある

**デフォルトの名無しさん** · 2021/02/23(火) 17:50:04.63

>>16
誤解のない意思疎通のために必要なら
一時的なものでもドキュメント書いた方が結果的に安上がり

ルールとか規約のためだけに書いてるものはだいたい無駄

**デフォルトの名無しさん** · 2021/02/23(火) 19:28:10.56

>>17
各ファイルのステップ数とか書き込むExcelとかに？

**デフォルトの名無しさん** · 2021/02/23(火) 20:09:46.89

>>19
そういうのは自動生成すればいいだけだからどうでもいい

**デフォルトの名無しさん** · 2021/02/24(水) 09:11:56.42

>>18
作って放置して逃げてきた自覚がありますか？

**デフォルトの名無しさん** · 2021/02/24(水) 09:20:29.14

ほとんど仕様どうりに作れない、特に今は

**デフォルトの名無しさん** · 2021/02/24(水) 12:25:09.13

Linux界ではよくソースが仕様書と言われます。

**デフォルトの名無しさん** · 2021/02/24(水) 14:34:55.93

枯れてるJavaとかならなぁ、flutterとかだと新しいプラグインで「あーこんなやり方あるの？/できないの？」みたいな事も多いからなぁ
ListView.builderの中のListView.builderとか一工夫必要だしなぁ
API mockでプロトタイプアプリ作ってエンドと合意してから要件他まとめる感じ

**デフォルトの名無しさん** · 2021/02/24(水) 17:07:52.91

linux kernel読むのにソースだけ読み始めても無理があるだろ。
明らかにドキュメントが必要だし、実際役に立ってる。

**デフォルトの名無しさん** · 2021/02/26(金) 03:55:10.19

>>24
地図のZ社のカーシェアアプリ？

**デフォルトの名無しさん** · 2021/02/26(金) 05:54:24.34

Ruby では、ソースコードのクラス定義やメソッド定義箇所に、

YARD の記法に従いコメントをつけることで、自動的に文書が作られる

**デフォルトの名無しさん** · 2021/02/26(金) 09:46:35.99

>>14
コード書かない人が仕事したことを装う為に必要

**デフォルトの名無しさん** · 2021/02/26(金) 11:12:08.06

>>28
書かせるのが仕事なんだから
コード以外にもたくさん書かせたほうが仕事ができる男なんだよ

**デフォルトの名無しさん** · 2021/02/26(金) 11:13:03.78

役に立つドキュメントを書ける人とそうでない人がいる

**デフォルトの名無しさん** · 2021/02/26(金) 13:38:55.78

>>30
これはそうだな
本当に役立つドキュメントを書ける人は20人に1人もいない

**デフォルトの名無しさん** · 2021/02/26(金) 14:09:11.03

まあそれはコードでも同じなんだが、コードの場合糞でも動くってところが厄介。

**デフォルトの名無しさん** · 2021/02/26(金) 14:46:17.25

ドキュメントはクソでも動かさないから修正されない
ドキュメントこそクソができないようにレビューしなければいけないのだが
クソでも動かさないから間違っていても客から文句は言われないのでレビューもしない
ドキュメントがクソだとコードはクソにしからない、これはドキュメントのせい
ドキュメントがクソ方がもっと厄介

**デフォルトの名無しさん** · 2021/02/26(金) 14:51:22.12

そだよ
上流ドキュメントの質が一番重要だから君たちより高い金もらって
ドキュメントだけ書いてあとは君たち下請けに投げてるんじゃないか
クソの下請けがクソにしかならないのは当たり前

**デフォルトの名無しさん** · 2021/02/26(金) 14:52:39.36

>>34
だからドキュメントのレビューさせろって言ってるんだが？

**デフォルトの名無しさん** · 2021/02/26(金) 16:04:06.59

>>34
糞しかできないんじゃその高級なドキュメントとやらに価値はないがな。

**デフォルトの名無しさん** · 2021/02/26(金) 17:17:33.51

>>36
そだよ
客は本当の価値なんて分からないから下請けがクソでしたってことにして清算するだけ
本当の価値に対して金が動くわけじゃないから

**デフォルトの名無しさん** · 2021/02/26(金) 17:23:04.47

>>35
すればいいじゃんw
レビューすらさせて貰えないのは君の会社の管理体制の問題だろ
その程度の交渉力すらないならドキュメントの質に関係なくクソ確定だよ

**デフォルトの名無しさん** · 2021/02/26(金) 18:04:11.49

ドキュメントの内容が正しいか
ちゃんとテストしましたか？
テストは重要ですよ

**デフォルトの名無しさん** · 2021/03/03(水) 12:36:34.16

>>33
これは本当にそう思う

・ドキュメントはテストできない
・ドキュメントは静的解析できない

これがドキュメントの抱える最大の問題

まあ静的解析はできなくもないが
標準的なエコシステムが無いのでコストが高すぎる
独自のエクセル設計書解析システムを持ってる現場で働いたことがあるけど
解析が重すぎ&成果しょぼすぎて全く役に立ってなかった

**デフォルトの名無しさん** · 2021/03/03(水) 13:41:07.73

ドキュメントもテストできるよ
自動化はまだ難しいだろうけど

**デフォルトの名無しさん** · 2021/03/03(水) 20:42:50.69

そもそもテストが必要になる時点でクソドキュメントだけどな。

**デフォルトの名無しさん** · 2021/03/03(水) 21:37:51.18

だから全てのドキュメントは、クソドキュメントだからテストするんだよ

**デフォルトの名無しさん** · 2021/03/03(水) 21:54:41.54

ドキュメントをレビューする時に何をレビューしてんの君たちww

**デフォルトの名無しさん** · 2021/03/03(水) 22:02:48.37

ドキュメント作ってるやつがレビューをさせないんだよ
バグありのまま出来ましたって出してくる
大量に持ってくるからその場でレビューできる量じゃない
そして実際に作ってる段階で漏れや矛盾が見つかる

**デフォルトの名無しさん** · 2021/03/03(水) 22:20:48.99

>>45
意味がわからん
受け取る側が勝手にレビューすればいいじゃん
その場でレビューする必要なんてないぞ

**デフォルトの名無しさん** · 2021/03/03(水) 22:26:42.67

納品するやつが受け入れテストさせねーんだよ
バグありのまま出来ましたって納品してくる
そして実際に運用してる段階で不具合が見つかる

検収とか受け入れテストとかすれば良くない？

**デフォルトの名無しさん** · 2021/03/03(水) 23:26:40.83

>>47
なんで御社はそんなところに発注してんの？

**デフォルトの名無しさん** · 2021/03/04(木) 09:54:52.43

>>46
スケジュールの問題、遅れて遅れまくった上に
これで作れと言ってくる
レビューしてバグを戻すと、更に開発時間が減る

**デフォルトの名無しさん** · 2021/03/04(木) 09:56:46.29

そもそも下流でレビューするという工程が含まれてない
上流に戻すという工程が含まれてない