Agile Manifestoには以下のように書いてあります。 動作するソフトウエアは包括的なドキュメントにまさる ともするとドキュメント軽視と取られかねない宣言です。この宣言を誤って解釈してドキュメントはいらないとなる場合もあるかもしれませんが筆者はそれは間違いだと思っています。この宣言では包括的なドキュメントよ
![プロダクト開発でドキュメントを書かないとどうなるか](https://cdn-ak-scissors.b.st-hatena.com/image/square/b384a3eca6e7c3a1dd570097d73a2044a816bbae/height=288;version=1;width=512/https%3A%2F%2Fs3.ap-northeast-1.amazonaws.com%2Fwraptas-prod%2Fpro-dev%2F2c981f18-e992-4410-bb26-6a5fd87343c2%2Ffbf43efc1681f3bf8a03b84ba42e978e.png)
5月のThoughtWorksのTechnology RadarでもADOPTされたADRという手法について、面白かったので、ざっくり自分なりに調べたメモです。 Technology Radarでは以下のように述べられています。 多くのドキュメントは、読みやすいコードとテストに置き換えることができます。しかし、進化的アーキテクチャでは、将来のチームメンバーの利益と外部の監督のために、特定の設計上の決定を記録することが重要です。Lightweight Architecture Decision Recordsは、重要なアーキテクチャー決定を、そのコンテキストおよび結果と共に取り込むための技法です。これらの詳細は、WikiやWebサイトではなくソース管理に格納することをお勧めします。そうすれば、コードと同期したままのレコードを提供できるからです。ほとんどのプロジェクトでは、この手法を使いたくな
01_ADR.md アーキテクチャ設計のドキュメンテーション コンテキスト アジャイルプロジェクトのアーキテクチャは、別々に記述され定義されなければなりません。すべての意思決定が一度にされるわけでもなく、プロジェクト開始時にすべての意思決定がされてるわけでもありません。 アジャイル手法では、ドキュメンテーションに反対はしませんが、価値のないドキュメンテーションはいけません。チーム自身の助けになるようなドキュメントは価値がありますが、ちゃんと最新化し続けなければなりません。膨大なドキュメントでは、最新化されなくなることでしょう。小さくまとまりのあるドキュメントは少なくとも更新される可能性はありますよね。 また膨大なドキュメントはだれも読みません。たいていの開発者はソースコードサイズの合計よりも(byte的な意味で)大きな仕様書が書かれたプロジェクトを少なくとも1回は経験したことがあるでしょう
Architectural Decision Records (ADRs) An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) cap
アーキテクチャの検討を記録するADR(Architectural Decision Records)の方式で、自身がADRを採用するか検討した。 ステータス: 承認 決定者: @niku 日付: 2020-05-19 文脈と問題点の説明 ソフトウェア開発中に、あるアーキテクチャを採用した理由を知りたいことがある。 幸運にもそのアーキテクチャを採用した開発者にインタビュー可能で、また開発者の記憶が定かであれば、当時どのような状況・どのような選択肢が用意されている中から選択したかを明らかにできる。 しかしそうではなかった場合、過去に採用したアーキテクチャを盲目的に受けいれたり、完全に無視するといった不健全な意思決定を強いられることになる。 そこで、決定の粒度が大きくかつプロダクトの品質に大きく影響を与えるアーキテクチャ上の変更の「なぜ」を記録し、時間が経過した後も簡単にアクセスできるよう AD
こんにちわ。てぃーびーです。 最近システム開発界隈でたまに話題をみかける「ADR」。 ADR は Architectural Decision Records の略で、アーキテクチャーの意思決定を決まったフォーマットで記録し続ける手法です。アーキテクチャーの意思決定後、時間の経過とともに当時のアーキテクチャーを設計した人が異動や退職で不在になり、後任が現在の設計を検討する上で、なぜ現状のアーキテクチャーになっているか確認したい、といったときがこの記録が活用される典型的なケースです。それ以外にも人の記憶は不確かなため、意思決定をした本人にとっても記録は便利です。 そういった必要性に関して niku さんの以下の記事が参考になります。 2020-05-19 ADR(Architectural Decision Records)を書くと決めた理由を自分の言葉で書き出した|ヽ(´・肉・`)ノ|no
自分もデザインドキュメントを始めようと思ったので、デザインドキュメントとは何かを知るために情報収集した結果と簡単な自分の考えのまとめ。 デザインドキュメント概要 [2007-06-01] Software Engineer in Google - Google Developer Day Tokyo 2007 Googleのソフトウェアエンジニアがどのように開発しているのかという発表で、プロダクト開発の流れの中でデザインドキュメントを利用していることが説明されている Why(背景や目的)、How(おおまかな設計、コードを見てわかることは書かない)、Who(メンバ、誰にコンタクトすればそのプロダクトについて知れるか)、セキュリティやプライバシーに関する考慮、テストやモニタリングをコーディング前に記述する。開発を進める中でできるだけ乖離しないように修正する。 この発表内容に関する聴講者のメモ:
この記事はMicroservices Advent Calendarの17日目の記事です。前回は#0: マイクロサービスの構築プロセスのお話でした。 はじめに マイクロサービス・アーキテクチャの話は多くありますが、実際にマイクロサービスを新たに設計・開発するとき、どのような手順を踏むか、と言ったことを扱った文献はそれほど多くない印象です。そこで、自身の経験を元に、マイクロサービスの設計をどのようにしているか、ポイントをかいつまんで説明したいと思います。 前回は、あるマイクロサービスの構築プロセスを外観しました。今回は、一歩踏み込んで、マイクロサービスの責務を定義する話になります。 デザイン・ドキュメントを書こう 新しいマイクロサービスを作る前に、1枚のデザイン・ドキュメントを書くべきです。まず、作ろうとしている マイクロサービスの目的(責務) を書きましょう。それ以上のフォーマットは設けて
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1~2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文: www.industrialempathy.com 関連書籍: Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安:11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
こんにちは、 @kz_morita です。 先日行われた勉強会 でデザインドキュメントというソフトウェア開発時に各ドキュメントについて聞いて,興味が湧いたのでしらべてみました. デザインドキュメントとは デザインドキュメントは Google などの企業でソフトウェア開発を行う際に一緒に書かれるドキュメントのことです. ソフトウェアがどのような問題をどのように解決するのかを,ソフトウェアよりより高いレベルで伝えるための手段としてもちいられます. 何を書くべきか このドキュメントには,実装のアプローチや,主要な設計上の決定事項,考慮されたトレードオフなどが書かれます. 何を書くべきかという明確なルールはないためそれぞれのプロジェクトに合った形で改造していくのが良さそうです. 以下に自分が参考にした一例を載せます. - プロダクト開発・機能開発・改善の背景 - 課題は何か=何を解決するのか -
前提 ここで言っているドキュメントは仕様書ではなく、顧客向け製品ドキュメント。 ミドルウェア製品を開発 小さなチーム パッケージ製品とパッケージ製品のクラウド版 そのため顧客に提供するドキュメントが必ず必要 GitHub を利用 自分で開発する場合のフロー 作りたい機能をぼんやりでいいので GitHub Issue に追加する feature ブランチを切る デザインドキュメントをリポジトリの doc/ 以下に書く デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる デザインドキュメントは書き捨て前提で、とにかくメモを書く 製品ドキュメントを書き始めて、一旦書き終える ブランチマージに向けてコーディングを進める 書ける範囲でテストを書く ドキュメントを平行して修正する プルリクエストをだしてレビュ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く