最近開発用のドキュメントをどこに配置するか悩んでて、いくつか試して見てる。今回言っている開発用のドキュメントというのは、コードの触り方も含んだサービスの開発に関するもの。例えば 開発環境セットアップ方法 ページに表示している広告をどのように切り替えたりするか(googleの管理やコードの変更も含めた) サービス内の特定の機能の仕組み 内部用HTTP APIドキュメント などを指している。 結構いろいろ考えるところがあるので、思っていることをまとめてみたい。一応先に結論を言っておくと 基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う あといろいろ悩んでるので事例あったら教えてください。 起きている問題 ドキュメントは
時々組織の内外で盛り上がるネタの一つに「設計書は必要なのか」談義がある。今回も後輩の一人から設計書不要論がぶつけられてきたので、現時点での個人的見解をまとめておくもの。個人的には、ソフトウェアの設計書は必須でもないし、開発戦略を練る段階で作成するかどうかを決めればいいと思っている。 議論の前提：仕様書と設計書 議論を簡単にするために、まず「仕様書」と「設計書」という言葉を再定義しておきたい。今回の整理は以下としている。 仕様書 … 開発者とユーザー(仕様決定者)が、ソフトウェアの振る舞いや動きに関してコミュニケーションするために必要な文書類のこと。 設計書 … 開発者どうしがソフトウェアを作成するにあたっての、構造や仕様についてコミュニケーションするために必要な文書類のこと。 要は今回議論しようとしている「設計書」は、ユーザー(仕様決定者)とは無関係なものであるという前提である。また、ここ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く