設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ
はじめにTIG真野です。 秋のブログ週間2023 の3本目は、設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします。 前段として6年前、「我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか」という記事を書いたのですが、その後の試行錯誤はどこにも残していないことに気づきました。普段のフューチャー技術ブログですとちょっと引け目を感じるテーマですが、秋の夜長を楽しむため読み物成分を多めに書くというテーマのこのブログリレーにピッタリな気がするため、この機会をお借りします。 ドキュメントも色々な種別があるかと思いますが、この記事では設計ドキュメントを指すことにします。設計ドキュメントは開発メンバーが参照するもので、ステークホルダーへの説明資料に引用して使うことはあれど、主目的は異なるという前提です。Design Docの場合もありますし、システム構成図、ERD、
君のプロジェクトにデータシートはあるか：101回死んだエンジニア：エンジニアライフ
いろいろな仕事を渡り歩き、今はインフラ系エンジニアをやっている。いろんな業種からの視点も交えてコラムを綴らせていただきます。 ■内部向けドキュメントが抜けている どんなプロジェクトでも、必要なドキュメントってあると思う。いろいろなプロジェクトに携わってきたけど、どこにも共通して言えることがある。 内部向けのドキュメントが貧弱である。 お客様に提出するドキュメントはきちんとレビューまでするが、内部向け資料は、ドキュメントどころか一子相伝の口頭伝授だったりすることも多い。なんだ、この差は？ やりづらくて仕方ない。 ■何を見てドキュメントを書くか ここで1つ、疑問に思うことがある。外部向けのドキュメントだが、いったい何を見てつくっているんだ？ ということだ。最近のサーバ製品や、レポート作成ツールは優秀だ。このツールを起動して、パラメータを手書きでExcelに貼り付けているのをよく見るが……。 ち
ドキュメントが更新できない理由：101回死んだエンジニア：エンジニアライフ
いろいろな仕事を渡り歩き、今はインフラ系エンジニアをやっている。いろんな業種からの視点も交えてコラムを綴らせていただきます。 絶対的情報量が多すぎる 思えば紙を使って仕事をしていた時代は良かったのかもしれない。紙は劣化するので、作成したドキュメントは書き直されたり追記されたりと、自然に行われていた。また、手書きなので複雑な書式で書くことが難しい。欠点のようだが、複雑に書けないが故に自然にシンプルで分かり易い形にまとめる習慣がついていたのかもしれない。 アウトプットできる情報の量が少ないので、手元に存在する情報の量も少なくなる。一見、乏しい情報を元に考えるので、思考の効率が落ちそうな気がする。しかし、一つのテーマに対してじっくり考える時間が取れるので発想がクリエイティブだった。情報の量が多いということは、その分、処理をするのが大変になるということだ。アドバンテージになるとは限らない。 当たり
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
