ドキュメントを書く技術 - blog

READMEを始め、ソフトウェアのドキュメント全般を書く技術というものをもっと洗練させていきたい。要件定義書のようなものだけでなく、開発方針や設計方針、API定義などなど。 これらのドキュメントをしっかりと整備するだけで、レビューの質も上がり新しい人が入ったときもスムーズに意識のズレなく開発ができる。はずだが、なかなかドキュメントの上手い書き方や管理の仕方というものは、コーディングのそれとは違い議論が活発ではない。 最近試してみたこと そういったドキュメントの中でも、"開発方針"や"設計思想"をどう残していくかということを考えている。それらを残しておくことで、コーディングのときも立ち戻る場所ができ、大きく道を踏み外さなくなる。 例えば、レイヤードアーキテクチャのようなものの"境界"をドキュメントにしていく。MVCでもクリーンアーキテクチャでも何でも良いけど、それらのアーキテクチャではそれぞ

[miyatakesan]

同意。自分の周りではドキュメント担当は非技術職みたいな風潮があるが、結局エンジニアリングの深いところの知見は必要。ただ、整理のための整理するようなコンサルのドキュメントはクソ。

[yoshiko_pg]

“個人的に各レイヤ(controllersやmodelsといったディレクトリ)にひとつずつREADMEを置いていくのが好きなのだけど、最近はそこに「MUST(MUST NOT)」、「SHOULD(SHOULD NOT)」、「MAY」などを書くといいのでは？と思って書き始めている”

[SWIMATH2]

各ディレクトリでREADMEに書くのよいな。外部wikiとかに書くよりコードレビューに組み込まれた方がメンテされやすそう

[turanukimaru]

Javadocにはパッケージコメントと言うものが有ってほぼディレクトリにつけたコメントみたいなもの。なのだがIT土方やってると自分以外に書いてる人見たことないな。

[akatakun]

各レイヤにreadme置くのいいですね

[UDONCHAN]

参考になる

[richard_raw]

ディレクトリごとにREADME書くのいいですね。"境界"は意識しておきたいです。

[okbm]

http://yuzutas0.hatenablog.com/entry/2017/07/06/083000 を思い出した

[efcl]

よくディレクトリにREADME置いてる https://github.com/azu/large-scale-javascript/tree/master/docs とかはレイヤーのディレクトリのREADME.mdが元になってる。

[akabekobeko]

ルートの README からリンクしておけば ESDoc でまとめられそうだし、この方法を採用してみようかな。

[RabbitBit]

賛成。ベクトルの方向性合わせのようなもので、正しい方向性に労力が向かう仕組みを作る事は、時にエンジニアリングよりもエンジニアリングらしい。

[sonots]

ドキュメントを書かせる技術か

[Kaketan]

must と should

[sgo2]

ドキュメントとドキュメントが指してる現物との紐付け及び同期、時系列変化の記録etc.を考えると、リポジトリに一緒に突っ込んでおくのが手っ取り早いのは確か。

[ohbarye]

“ドキュメントを書く技術というのは、同時にドキュメントを"書かせる"技術でもある。コーディングと全く同じで、自分だけが書けても意味がなく、誰が書いても一定のレベルにすることが重要”

[naopr]

あー、これしっくりくる！

[kwhrtsk]

ディレクトリに置くのいいな。真似してみよ。

[wata88]

思想のような、コードを読み込まなければ感じ得ないようなことをドキュメントに書きたい

[mag4n]

個人的にはAsciiDocやJavadocみたいにコマンド叩いて一つにまとめて提供できる形にしてほしい。資料の一覧性大事。開発ディレクトリ毎に情報書かれると参照する側が大変だし共有漏れするし速度下がる。

[akulog]

よさみ

[tbpg]

"各レイヤ(controllersやmodelsといったディレクトリ)にひとつずつREADMEを置いていく"

[isdh]

いいと思う。markdown 覚えようとしない人にも覚えさせられるかな。

[riceplanting]

ドキュメント

[kumokaji]

本当にそう思います "ドキュメントを書く技術というのは、同時にドキュメントを"書かせる"技術でもある。コーディングと全く同じで、自分だけが書けても意味がなく、誰が書いても一定のレベルにすることが重要。"

[h5y1m141]

"アプリケーション・組織独自の"境界"をドキュメントに残していく" なるほどー。QiitaTeamにこの類のドキュメント残してるけどこういう境界という発想無かったから参考にさせてもらおう

[marukan01]

ドキュメントを書く技術

[k-kurikuri]

これは素晴らしいアイデア

[Tomato-360]

とても良さそうに思える

[uskey]

境界毎に残しておくのよさそう。外部サービスに置いたりするとドキュメント類が散るっていう問題の解決にもなりそう。

[koogawa]

こういう指針があるとコードレビューも進めやすくなりますよね