improve README

README.md

@@ -1,8 +1,55 @@
-perldoc.jp のソースです。
+# NAME
 
-# 自前でうごかす方法
+perldoc.jp のソース
 
-## DBの準備
+# DESCRIPTION
+
+Perl の公式ドキュメント、モジュールドキュメントを日本語に翻訳したものを表示するサイト
+perldoc.jp のソースコードです
+
+# ARCHITECTURE
+
+perldoc.jpの翻訳データは、https://github.com/perldoc-jp/translation から取得し、
+SQLiteに保存しておき、それを表示しています。
+
+組み込み関数や組み込み変数などの一覧情報は、perldocの情報を元に生成しています.
+
+現在は、Japan Perl Associationが管理しているVPS上で動作しています。
+
+# WORKFLOW
+
+修正したい点があれば、プルリクエストを送ってください。
+
+# SETUP
+
+## Docker を利用する場合
+
+- Requirements
+  - Docker
+  - docker-compose v3 
+
+
+```shell
+# サーバーを立ち上げる
+make up
+
+# サーバーを落とす
+make down
+
+# テストを回す
+make test
+```
+
+## Carmel や Cartonを利用する場合
+
+- Requirements
+  - Git
+  - SQLite client
+  - Carmel or Carton
+
+### 下準備
+
+#### DBの準備
 
 SQLiteのDBが必要です。DBの場所は、config/development.pl に定義しています。
 そのままであれば、ユーザーのホームディレクトリの直下になります。
@@ -12,44 +59,35 @@ test ! -e ~/perldocjp.master.db && sqlite3 ~/perldocjp.master.db < sql/sqlite.sq
 cp ~/perldocjp.master.db ~/perldocjp.db
 ```
 
-## モジュールのインストール
+#### モジュールのインストール
 
 ```sh
-wget --no-check-certificates http://cpanmin.us
-perl cpanm --installdeps .
+carmel install
 ```
 
-## 翻訳データの取得
-
-git コマンドが必要です。
+#### 翻訳データの取得
 
 ※ `conf/development.pl` の `assets_dir` を変更しておくのをおすすめします(デフォルトでは、ホームディレクトリの直下に `assets` というディレクトリが必要になります)。
 
 ```sh
+# 翻訳されたpodの取得や必要なデータベースの構築
+# 翻訳データを更新したい場合もこのコマンドを実行します
 perl script/update.pl
 ```
 
-で、翻訳されたpodの取得や必要なデータベースの構築を行います。
+※翻訳データのアップデートを行いたくないが、関連するファイルやDBのみ更新したい場合は、`SKIP_ASSETS_UPDATE=1`を環境変数に設定してください。
 
-## plackup の実行
+### 開発をする
 
 ```sh
-plackup -Ilib -p 5000 app.psgi
-```
-
-勿論、PSGI based なので、Apache ででもなんででもうごきますけども。
-
-## 翻訳データのアップデートをするには
-
-最初の翻訳データの取得と同じです。
+# サーバーの起動
+carmel exec -- plackup -Ilib -p 5000 app.psgi
 
-```sh
-perl ./script/update.pl
+# テストを回す
+carmel exec -- prove -Ilib -r -v t
 ```
 
-※翻訳データのアップデートを行いたくないが、関連するファイルやDBのみ更新したい場合は、`SKIP_ASSETS_UPDATE=1`を環境変数に設定してください。
-
-## デザインを変更するには
+### デザインを変更する場合の環境構築
 
 デザインの管理には Scss をつかっています。
 Scss の生成は gem の Sass が必要なので