READMEの書き方

一般的なオープンソースプロジェクトで記載されている項目

●リポジトリ（プロダクト）の名前：Name
●概要：Overview
●デモ：Demo
●使い方：Usage
●環境：Requirement
●インストール方法：Install
●注意事項：Note
●文責：Author
●ライセンス：License

• オープンソースとエンタープライズ(内部向け)のリポジトリで書くべきことに違いはあるか？

参考資料

• 素敵なREADMEの書き方✨
• わかりやすいREADME.mdを書く
• 【超初心者向け】はじめてのREADME.md

参考資料

ドキュメント作成の方針(Why, What)

• 設計書には何を書くべきなのか
• 我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか
• ソースコードは設計書であり、コーディングは設計作業である
• プログラムの「アーキテクチャに関するドキュメント」は面倒でも書くべき、ではどのように書くべきか？
• いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。
• 敢えていま読む「仕様書の基本と仕組み」とシステム開発全体の流れ markdownサンプル

どうやって作るか(How)

• ドキュメントを書くときの「メンタルモデルの原則」
• gitbookで設計書を作成したら最高だった話
• draw.io で書いた画面設計書いてみたらストレスフリーになった 〜 続・gitbookで設計書を作成したら最高だった話
• Excel設計書を抹殺したくて4年前にWiki設計書を導入したら、意外とちゃんと開発回ってた話。
• システム構成図をテキストで
• draw.ioでAWSのインフラ構成図を書く
• AWS構成図を腐らせないで管理し続ける方法 with draw.io

作成すると良さそうなドキュメント

PRD

プロダクトの仕様を簡単にまとめたもの

ユースケース

参考資料

• スタートアップのための製品要求仕様書(MRD & PRD)の書き方

Architecture.md

システムのアーキテクチャを簡単な図とテキストでまとめたもの。

目的としてはプロジェクトに新規に参入した人が全体像を簡単に把握するためのもの。

参考資料

• ARCHITECTURE.mdというものを書いてみた
• プログラムの「アーキテクチャに関するドキュメント」は面倒でも書くべき、ではどのように書くべきか？
• 開発者が考える提案書テンプレート markdown版 - Qiita
• 開発者が考える提案書 補講 - Amazon流Internal Press Releaseテンプレート - Qiita

自動ドキュメント作成

おもにシステムやプログラムの仕様について

フロントエンド

• Componentカタログ
  • Storybook
• 依存関係可視化
  • madge

バックエンド(Python)

• 依存関係可視化

  • Pyreverse(pylintに統合された？)

• ER図

  • SchemaSpy
  • tbls

参考資料

• まだER図の管理で消耗してるの？ SchemaSpy でER図を自動生成して管理する　
• DBドキュメント（ER図など）を自動生成してくれるツールーschemaspy, tbls
• VueやReactでコンポーネントやモジュールの依存関係を把握する
• [python] クラス図を自動生成する

• 個人開発でもADR （アーキテクチャデシジョンレコード）を書くことの利点 - laiso