ARCHITECTURE.mdというものを書いてみた - maru source

こんにちは丸山@h13i32maruです。システム全体を簡単な図とテキストでまとめる「ARCHITECTURE.md」というものを最近知りました。これは良さそうと思い、JasperのARCHITECTURE.mdを書いてみました。 jasperapp/jasper/ARCHITECTURE.md ARCHITECTURE.md自体の目的は「プロジェクトへの新規参加者が全体像の把握を効率的に行えるようにする」という感じです。書き方の指針や注意点などは考案者による記事を見てもらうのがよさそうです。また良いサンプルとしてrust-analyzerというOSSのARCHITECTURE.mdが紹介されています。 https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html https://github.com/rust-analyzer/ru

[h13i32maru]

書きました。誰かの何かの役に立つといいな〜

[MonMonMon]

こういうのあるとCode Readingしやすいですよねー

[gettergot]

凄くいい 俺もやろうかな

[akio624]

Sourcetrailで色々構造解析してますが、このレベルの資料が最初からあると助かるな

[proverb]

良さそう

[mizdra]

丁寧に読者のメンタルモデル考えるところから始めるの良いなー

[externalight]

大事。

[kuborn]

優しさ大事

[hacktk]

真似したい

[cu39]

「その読者がARCHITECTURE.mdを読み終わったら、「不具合の調査や機能追加をするために、どのあたりのコードから見ればよいのか、探し方がわかる」という状態になるのを目指します」

[ifttt]

“Google図形描画” 知らんかった。いいなこれ

[braitom]

JasperのARCHITECTURE.md。やっぱARCHITECTURE.mdあるといいな

[maruware]

良い

[kazoo_oo]

よさそう。

[lizy]

UMLだと配置図～コンポーネント図あたりになるのかな

[k-wacky76]

今はこういうのUMLでは書かないんだな…

[surume000]

いいね

[dot]

良さそう

[ImpureSilver11]

いいなこれ、参入時めっちゃ欲しくなるやつだ。

[aike]

ドキュメントとして一番ほしかったやつだ！今後流行るといいな。

[codingalone]

あー必要だよねこういうの

[p1ass]

書いてみようかな

[Shisama]

めっちゃいい。読み手の期待(メンタルモデル)を書く前に定義しておくことで、それを意識した文書を書くことができる。これどんな文にも使えそう。あとARCHITECTURE.mdって名前でコードの近くに置いてるのも良い。真似る

[khigashigashi]

メンタルモデルとドキュメント、すこー

[u_tis]

めっっっちゃいい