開発のドキュメントをどこに置くか問題 - $shibayu36->blog;

最近開発用のドキュメントをどこに配置するか悩んでて、いくつか試して見てる。今回言っている開発用のドキュメントというのは、コードの触り方も含んだサービスの開発に関するもの。例えば 開発環境セットアップ方法 ページに表示している広告をどのように切り替えたりするか(googleの管理やコードの変更も含めた) サービス内の特定の機能の仕組み 内部用HTTP APIドキュメント などを指している。 結構いろいろ考えるところがあるので、思っていることをまとめてみたい。一応先に結論を言っておくと 基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う あといろいろ悩んでるので事例あったら教えてください。 起きている問題 ドキュメントは

[shiba_yu36]

昨日議論した内容書いた。この辺結構難しい

[t-wada]

“基本は実装に一番近いところにコメントとしてドキュメント書くのが良くて、とはいえ導入ないと分からないよなという部分には俯瞰できるように図とか置いておきたい”

[masa8aurum]

特に知らないことはなかったけど、ドキュメントの運用について考える参考になったので。

[dev0000_1]

古い記事が上がってきたな。最近はgitもwikiもファイルも全部backlogに突っ込んでいる。

[houyhnhm]

パターン化する事が一番重要。トップフォルダにreadme入れてそこにインデックス作っとくとかはよくやる。

[greenT]

れっどまいんのうぃきとかに書くんでは？

[tdtsh]

環境構築などのサマリはREADMEに書きたい

[rti7743]

できるだけコードの中に一票。　あちこちの処理に依存しているなら、その処理を呼び出す発火点となる親玉に乗せておきたい。それと、htmlメールのようにコードにも絵とか貼れればいいのになあ。

[efcl]

ドキュメントをどこに書くか。 プログラムコードでもハイパーリンクがもっと普通に使いたい

[oooooooo]

文芸的プログラミング

[iww]

プロジェクトにdocフォルダ作って全突込み＆管理

[mabots]

ドキュメント置き場

[trashtoy]

ポリシーを決めても結局ケースバイケースになりがちで、判断が難しい

[kimutansk]

「基本は実装に一番近いところにコメントとしてドキュメント書くのが良くて、とはいえ導入ないと分からないよなという部分には俯瞰できるように図とか置いておきたい」はいいですが、やはり結構抽象的

[tmtms]

だいたい似たような感じで運用中。図は変更コストが高いので極力避けたい。グループウェアは使ってない。最終的にはマニュアル作るので非エンジニア向けにはそれで。

[sassy_watson]

ドキュメント見つからない問題はけっこうぶち当たるので、実装に近いとありがたい

[JD30671011]

悩ましい、更新の手間と参照・検索性を保ちつつソースに近いところが利便性はいいんだなぁと思いつつも、実ソースよりヘッダのコメントの方が行数稼ぎそうになったり、、、日々悶々としています。

[moznion]

色々なコードが強調して動いてる部分、ドキュメントあると本当に助かるし、更に図がついてるなんて最高

[kenjiskywalker]

作業計画書とか作業ログとかもrepositoryに入れる試みしてる

[hakobe932]

ドキュメントたしかにむずいので参考になる