「わし詳細設計書書くのやだよ」システム開発で細かければ細かいほど仕様変わった時の変更が爆増してメンテコスト爆上がりする。かけるべきコストはそこじゃない話に賛否両論
しのゆ𝕏酒くずエンジニア @shinoyu 新宿で社長やってるソフトウェアエンジニア18年生のおかまちゃん / 💻技術🎧 V系 🎀ロリィタの人 / 170スペ110 スプリング、骨ウェーブ、顔ソフエレ / 絡みない鍵とスパムは🚫 / 原則IT関連業のみフォロー /たまに会えるかも @shinjukudist しのゆ𝕏酒くずエンジニア @shinoyu わし詳細設計書書くのやだよ(￣･ω･￣) 細かければ細かいほど仕様変わった時の変更が爆増してメンテコスト爆上がりする。かけるべきコストはそこじゃない。 必要なのは完成に必要要件がまとめられたもの。それを元に受け入れ試験書がつくられる。それクリアすればどう作ってようが構わんわけだ 改修コストを下げるための設計になってることは前提だけどね。 だけど、詳細設計書が必要となる現場はこの設計することはできない。だってそれできてたら詳細設計書
社内ドキュメントはなぜ更新されないのか？情報の鮮度を最小限の運用負荷で維持する「イミュータブルドキュメントモデル」のススメ - KAKEHASHI Tech Blog
はじめに こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。 プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。 しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけた
[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita
下記ドキュメントバージョンに関する注意点です。 バージョン番号のルールを定める：バージョン番号は、どのようにつけるかルールを定め、チーム全員が同じ理解で使用するようにする必要があります。たとえば、変更内容によって数字がどのように増えるか（major, minor, patch）、何桁で表現するかなど、具体的に決めておくことが重要です。 変更履歴を明確にする：どのような変更があったのか、それがどのバージョンで実施されたのかを明確にすることが必要です。これにより、何らかの問題が発生した場合に、どのバージョンから問題があるのか特定することができます。 ドキュメントの保存場所を一元化する：ドキュメントのバージョン管理には、ドキュメントを保存する場所を一元化することが重要です。それにより、異なるバージョンのドキュメントが、複数の場所に分散してしまい、誤ったバージョンが使用されることを防ぐことができま
![[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/d7d131e38e26f54466aece3306435a4c09990de8/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fcdn.qiita.com%252Fassets%252Fpublic%252Farticle-ogp-background-412672c5f0600ab9a64263b751f1bc81.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk3MiZoPTM3OCZ0eHQ9JTVCRG9jJTVEJTIwJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgzJTg2JUUzJTgzJUIzJUUzJTgzJTk3JUUzJTgzJUFDJUUzJTgzJUJDJUUzJTgzJTg4JUUzJTgzJUJCJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgxJUFFJUU2JTlCJUI4JUUzJTgxJThEJUU2JTk2JUI5JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnR4dC1jb2xvcj0lMjMyMTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmcz01MjE0ZDhhMTY1ZjE1ODIxNGE5NzU4Njc3MTNjOTBmNg%26mark-x%3D142%26mark-y%3D57%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZoPTc2Jnc9NzcwJnR4dD0lNDBzeWFudGllbiZ0eHQtY29sb3I9JTIzMjEyMTIxJnR4dC1mb250PUhpcmFnaW5vJTIwU2FucyUyMFc2JnR4dC1zaXplPTM2JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnM9MTc4MmM0MTlmNzhiYTJjNTk0ODYwZmExZDc0OWYzNjQ%26blend-x%3D142%26blend-y%3D486%26blend-mode%3Dnormal%26s%3Db088349e276a1ebcdb9dcf1e2d753094)
納品ドキュメントの作成にMarkdown+Vivliostyleを採用した話 - Qiita
こんにちは、製造業でソフト開発エンジニアをやっているとみー(@tommyecguitar)です。 会社で納品物の説明ドキュメントを作ることがあり、その時にMarkdownでの組版をやってみたので、どう運用したか、困ったところ、いい点、悪い点をまとめてみようと思います。 Vivliostyleで組版したブログはたくさんあるので、見た目がどんな感じにできるかなどはそちらを見ていただくか、Vivliostyleのサイトをご覧ください。 Wordじゃだめなのか。 製造業で何かしら長大なドキュメントを作るとなったら、大抵はWordを複数人数で編集するという運用をしているところが多いと思います。 しかし、Wordにはいろいろと悪いところがあります。 チーム内で共同編集すると、編集したところが消えたり、フォントやデザインがなぜか統一されなかったりする。 セクションごとに担当を分けても、マージが手作業にな
結局UMLとかシーケンス図とかAWSの図とかどれで描くと良いのよ？と思ったときの選択肢 - Qiita
自身のプライオリティによりますが、いくつか。 Markdownで幅広く再利用性を利かせたい、長期的に丁寧に版管理したい 自分自身の操作性、描きやすさと、見た目 俄然手軽に、短期的に、Onlineでいつでもどこでも いずれかという視点で考えると良いのかなと思い、並べてみました。 1. 長期的に: Markdownで幅広く再利用性を利かせたい、丁寧に版管理したいなら Markdownで描くことのメリットは再利用性。 将来的に追記・編集、自分以外の誰かが手を入れる可能性が高い。 現在のドキュメントだけでなく多種説明資料、媒体に転用する可能性がある。 ...という点で差分管理をしたいなら、以下。 VSCodeでPlantUML、Mermaid 上記参考で以下。 Alt+D でプレビュー起動。 Ctrl + Shift + P でコマンドパレットを起動し、出力。 png, svg, eps, pdf
設計書には何を書くべきなのか - terurouメモ
設計とは、 要求（やりたいこと）をヒアリングする 要求を要件（何を満たさないといけないのか）に落とし込む 要件を実現するために考えられる手段を洗い出す 手段の検証を行う 検証結果を元に、どの手段を使うかを選定する 選定した手段を合意する（一部要件を満たさない事項がある場合は、代替策や妥協ラインについても合意する） 合意内容を元に、実装や設定に落とし込む をやることである。画面設計や機能設計のように、3-5の検証/選定が薄くなったり曖昧になったりするものはあるが、一般化するとこの流れになる。 設計書には、上記の設計でやってきたことを順番に書いていけばよい。これを文章構成のテンプレに落としていくと、 要求 要件 方式 対応案（いわゆる比較表で書いていくのが楽） 検証結果 選定・合意結果（合意した代替策や妥協ラインについても記載する） 詳細設計（どういう実装にするとか、パラメーターにするとか、細
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。｜Fritz | Lead Product Manager @ Mercari
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。 こんにちは、フリッツ です。今回はプロダクトマネージャーの日課とも言える「仕様書」について。自分にとっては PM 業の施策実行フェーズにおいて最も重要な仕事のひとつであり、最も心躍り、最も興奮する瞬間です。 PM になってかなりの時間が経ちましたが、「仕様書」への力の入れようは減るどころか、「もっと気合を入れなければ。」と感じる一方。在宅勤務が（たぶん） IT 業界のニュースタンダードとなっていくいま、なおさら「仕様書」の重要性を訴えたい今日この頃です。 ということで、今回は ・ 良い仕様書がもたらす 5 つの効果 ・ 仕様書の重要性が増していく 2 つの理由 ・ 仕様書に含めたい 14 の項目・実戦編 ・ 仕様書作成時に心に留めたい 3 つのこと ・ 具体的な仕様書サンプル（
[設計]SQL設計書の書き方（続き） - PSI Labs
こんにちは。shintaniです。 前回のSQL設計書（データ取得図）の記事 の続きです。 今回はGROUP BYやソート順の書き方、そしてインラインビューを使う場合と、書くときのポイントを説明します。 まずはGROUP BY とソート順。 （前回の紹介では書き忘れていました・・・） ソート順とグループ化項目の位置に違和感を覚える方もいるでしょう。 しかしソート順は図に書いた理由の他にも「SELECT項目がどう並ぶか？」という観点から、SELECT句のそばにあった方が分かりやすいです。 そしてグループ化項目は「テーブル結合後にどう集約するか？」なので、図の下にあった方が分かりやすいです。 次は インラインビュー。 こんな感じになります。 （インラインビューにしなくても出来る・・・というのは御容赦を） 書くときのポイントですが、 SELECT句はこだわらない。テーブル結合にこだわる です。
[設計]SQL設計書の書き方 - PSI Labs
お久しぶりです。shintaniです。 今回はSQLの設計書について書いてみます。 とはいっても「正しいSQLの設計書」などとおこがましいことを言うつもりはありません。 「今までより多少マシなSQLの設計書」という程度に捉えて下さい。 このような帳票があるとします。 これに対して、下記のような詳細設計書（SQL設計書）を書いているプロジェクトが結構あるかと思います これでは殆どSQL自体を書いているのと変わりません。 テーブル同士の繋がりや絞り込み条件も分かり辛いです。 これに対し、下記は私が以前関わったプロジェクトで作ったSQL設計書です。 （そこでは ”データ取得図” と呼んでいました） これはE-R図とは異なるものです。 あくまでSQLの結合方法や条件設定などを記述したものです。 この形式のSQL設計書には以下のようなメリットがあります。 ----------------------
![[設計]SQL設計書の書き方 - PSI Labs](https://cdn-ak-scissors.b.st-hatena.com/image/square/a48339196b9597fc66f712acf9e70fe7f330195d/height=288;version=1;width=512/https%3A%2F%2Fwww.psi-net.co.jp%2Fblog%2Fuploads%2F2017%2F03%2F1490567663_58d841ef951b6.JPG)
ドキュメントを書く技術 - blog
READMEを始め、ソフトウェアのドキュメント全般を書く技術というものをもっと洗練させていきたい。要件定義書のようなものだけでなく、開発方針や設計方針、API定義などなど。 これらのドキュメントをしっかりと整備するだけで、レビューの質も上がり新しい人が入ったときもスムーズに意識のズレなく開発ができる。はずだが、なかなかドキュメントの上手い書き方や管理の仕方というものは、コーディングのそれとは違い議論が活発ではない。 最近試してみたこと そういったドキュメントの中でも、"開発方針"や"設計思想"をどう残していくかということを考えている。それらを残しておくことで、コーディングのときも立ち戻る場所ができ、大きく道を踏み外さなくなる。 例えば、レイヤードアーキテクチャのようなものの"境界"をドキュメントにしていく。MVCでもクリーンアーキテクチャでも何でも良いけど、それらのアーキテクチャではそれぞ
我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか
フューチャーアーキテクト Advent Calendar 2017 の2日目です。 システム設計が大好きで大嫌いな皆さん、こんにちは。 突然ですが、皆さんはどのようにシステム設計における ドキュメント腐る問題 に立ち向かっていますか？ … ドキュメント腐る問題とは、設計時に作成した各種ドキュメントがGoogle Driveやファイルサーバ上で陳腐化してしまい、現状の正しい状態を指していないことです。せっかく新規参画者がキャッチアップしようとしてもドキュメントが真実を示していないという怖いやつですよね。 今まで出会った一番辛いドキュメントは、PJ初期に作成したホワイトボードに書かれたラフスケッチの画像しか無かったところですね。まず字が汚いし、内容も最新版と微妙に異なっていました。新規参画者殺しにもほどがあると、ほんのちょっとだけ恨みました。 いやいや、ちゃんとサボらず整合性を取れよって？サボ
システム開発の詳細設計書/内部設計書に書くべき内容・レベル
「詳細設計書ってどこまで書けばいいのかなぁ？」 「細かく書きすぎるとコード書くのと変わんなくなっちゃうし…」 「ざっくり過ぎると足りないし…」 通常の開発工程は、 要件定義 基本設計(外部設計とも言う) 詳細設計(内部設計とも言う) 実装 テスト と続きますよね。 この中でも詳細設計は軽視されがちで、きちんと設計を終えずに実装工程に入ってプログラミングを始めることも多いかと思います。 そうなってしまうのには理由があります。詳細設計書はプログラムを実装するのが誰かによって、書き方を変えるべきものだからです。 そんなわけで今回は「詳細設計に書くべき内容・レベル」を紹介します。 そもそも詳細設計書って必要？ 「いらないんじゃ…？」と思ってる方も多いかと思います。 実際、詳細設計書を作らないプロジェクトもたくさんあります。 趣味でコードを書く時も詳細設計書なんて書きませんよね。 なので、詳細設計書
Excel で仕様書を書く際に注意すること - Qiita
Excel で文章を書く際に注意すること Excel で仕様書をあちこちの会社で書いてきましたがどこの会社でもあまりメンテ性に考慮した使い方をしているところが少ないのが現状です。 Excel で文章および仕様書を書く際になるべく、あとあとメンテ性が失われないようにしたいものです。 文章を長くかかない Excel方眼紙反対派がよく言うことの１つに「改行がめんどう」というのがあります。 そもそも長い文章を書いていることに問題がある可能性があります。 簡潔に書くために、箇条書きなどを用いるのをお勧めです。AND条件やOR条件などで文章が長くなる場合には表を用いて表現しましょう。 セルの連結はなるべく使わない ヘッダ等では仕方がない部分はありますが、文章を記述する部分でセルの連結をすると著しくメンテ性が失われます。セルの連結はするべきではありません。 値の代入などは表を多用する 代入の記述などは文
MS Wordの使い方（その1）：おすすめ初期設定 | 悠雀堂ブログ
数回に渡り、Microsoft Word 2013（Word 2010も対象）のおすすめの使い方をレポートします。 第1回は初期設定編として、Wordが行頭の文字を勝手に変換したり、Webブラウザからコピー＆ペーストをする際に書式までコピーしてしまう機能を無効にします。 はじめに 前回の後半、Microsoft Office 2013の設定について書きました。今回はその中のWordに絞り、私の個人的おすすめ初期設定についてレポートします。 本稿は、以下のような感想を持たれている方を対象にしています。 Wordが行頭の「・」や「1.」を勝手に変えるんだけど…。 行頭の英文字を大文字にしないでほしい…。 Webページからコピペするとフォントや色をそのまま持ってきてしまう…。 記事中はWord 2013の画面を用いますが、Word 2010も同様の操作で同じことが可能です。 行頭の英字の自動修正
MS Wordの使い方（その2）：構造的な文書のススメ | 悠雀堂ブログ
このシリーズでは、Microsoft Wordを使った構造的な文書を作成するための設定と使い方をレポートする予定ですが、その前に本稿では「構造的な文書」とは何かから書き始めます。Wordの使い方は一切登場しません。（爆 はじめに 「構造的な文書」とは、ここでは章や節を意識する文書のことを指します。HTMLを書いたり、LaTeXを使ったことがある方はイメージしやすいと思います。具体的には以下の様な感想を持たれている方が対象です。 論理的な文書や技術文書を、早くきれいに書きたい！ 章や節の番号って、あとから章を追加すると書きなおさなきゃいけないよね。 リターン連打でページを替えているけど、文章を追加するとリターンの数も変えなきゃいけないよね。 既に見当が付いている方もいらっしゃると思いますが「スタイルのススメ」です。 Wordの設定の仕方や使い方をレポートする前に、本稿では構造的な文書の定義と
MS Wordの使い方（その3）：スタイルを設定する | 悠雀堂ブログ
Microsoft Wordには、昔から「スタイル」という機能があります。論理的な文書や技術文書を、を早くきれいに作成するためには必須の機能です。本稿ではWord 2013を例に、スタイルの設定の仕方をレポートします。 既にスタイルを利用している方も、もしショートカットキーを設定していないのであれば、ショートカットキーを設定することでさらに効率があがります。 はじめに 前回の「構造的な文書のススメ」では長々と「構造的な文書とは」について書いてしまいました。(^^ゞ 要約しますと、構造的な文書とは、「論理的な文書、技術文書、その他ビジネス文書などの、章・節・項が適切に設けられた文書」のことを指しています。 構造的な文書には、章・節・項に「見出し番号」が振られています。その作成途中には、章・節・項が適切になるようレベルを変えたり、順序を入れ替えたりします。また後から見た目を調整するために、文書
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
20231206_設計ドキュメント腐る問題、Git管理で運用してみた本当のところ
脱ExcelしたいMarkdownテンプレート目次 - Qiita
ドキュメントを作りたくなってしまう魔法のツールSphinx
コードの日本語訳みてえなバカな設計書とか、Excel 方眼紙がなくならない理由について、引用しながら考える - Murga