開発案件 におけるREADME.md のあり方

オープンソース開発とはちょっと違う、クローズドな開発案件でのREADME.md の書き方について考えてみました。

開発案件 における README.md

オープンソースプロジェクトにおいて、 README.md はランディングページとなっています。

このため、通常は詳細な使い方やソースの概要など様々な内容が記述されている事が多いでしょう。

案件においては、通常このような情報をランディングページとして掲載するメリットはあまり無いように思います。
プロジェクトの参加者には、使い方やソースのドキュメントについて、探索するだけの動機があります。

Wiki と README の使い分け

開発の進捗に応じて頻繁に変更される可能性のある内容については、Github などの リポジトリ管理サービスで提供されている Wiki を利用するという方法もあります。

README.md はあくまでソースコードの一部なので、運用状況では更新に Merger の承認を必要とする可能性もあります。

ドキュメントの保守を永続化する上でも、より少ないコミュニケーションコストで運用可能な Wiki の活用は可能な範囲で進めていくべきでしょう

Wiki の特徴

  • ページ分割して異なる関心のドキュメントを区分けできる
  • 編集を行ってもリポジトリのコミットを汚さない

** READMEの特徴 **

  • 多くのメンバーの目に触れやすい
  • リポジトリアクセス時最初に目に触れる
  • 変更がソースのコミットグラフ上に記録される

開発案件 における README.md のテンプレート

上記のような特徴から 以下のような構成で README を構築すると良いでしょう。

# Sample Project 

案件の概要をここに記します。
案件の概要をここに記します。

**LINKS**

- [案件主要Slack URL]()
- [Backlog 等要件管理ツールURL]()
- [GoogleDrive等ファイル管理ツールURL]()

## 導入手順

[プロジェクトのセットアップに関するWikiのリンク]()

## 環境構成

[プロジェクトの環境構成に関するWikiのリンク]()

...

案件の概要

案件名と案件の概要は必ず添えるようにしましょう。

リンク集として Slack などのチャットツールや Backlog / GoogleDrive など案件で主に利用するサービス群の URL もここに合わせて掲載しておくと、利便性が高まって良いです。

導入手順

導入手順やテストの構成などは別途 Wiki に記録して管理するのが良いでしょう。

テストの構成等は頻繁に変更が加わる可能性がありますし、導入手順に関しては様々なトラブルシュートを気軽に加筆掲載できる方が良いでしょう。

以下は導入手順資料のアウトライン例です。

# 導入手順

## プロジェクトのセットアップ

プロジェクトのセットアップフローについての解説を記述します。

- 事前にインストールが必要なソフトウェア
- セットアップに必要なコマンド類

### トラブルシューティング

プロジェクトのセットアップで起こりがちなエラー対応について記述します。

## 運用コマンド

運用上で必要なコマンド類について記述します。

## テスト構成

プロジェクト内でのテストの構成やLINT / CIについて記述します。

## コーディングガイド

最後に、コーディング規約や構成上の注意点等を添えます。

環境構成

テスト環境や本番環境の情報についても Wiki にまとめておくのが良いでしょう。

環境に付随するテストアカウントの認証情報等も記録して、メンバーの環境利用をより簡便にしておくと良いでしょう。
インフラ環境の構成自体は余り頻繁に変動しないかもしれませんが、環境ごと固有のテストデータ構成等、テスト利用時に必要な諸情報が気軽に更新できる形でまとまっていると開発の助けになるケースは多いでしょう。

Sendgrid や Papertrail などの外部SaaS を利用している場合は、それらの環境毎の違いにも触れておくと良いかもしれません。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です