日本語版ドキュメントの書き方マニュアルを作成する

[agektmr]

• この辺りにある .ngdoc をどのようにパースしてHTMLに変換しているのか。
• ドキュメントのサーブの仕組みはどうになっているのか。
• 日本語版ドキュメントをどこかにホストする場合、サーバーをどう調達するか。githubのpageでいけるのか。

辺りを明確にして、簡単なマニュアルを制作しWikiに掲載する。

[agektmr]

ひとまずここの下に日本語用のディレクトリを切って、.ngdocのフォーマットを崩さずに翻訳するだけなら作業を始めてしまって問題ないように思います。どうでしょう？

[agektmr]

@masakielastic

[craftgear]

質問もこのIssueで良いでしょうか？

[agektmr]

@craftgear ひとまずここを議論の場にしましょう。もちろん質問もして頂いて構いません。

[kurap]

どのようなプロセスで進むかんじでしょうか。

まず、課題をそれぞれ別のissueに分けて、議論の場は分けられたほうがいいかと。

[agektmr]

トピックが明確に分けられるなら、ご自由にissueを立ててくださって構わないです。どう進めるのかも手探り状態ですので、ここをひとまずの議論の場にできれば、と思っています。

プロセスについてですが、たたき台としてこういうのはどうでしょうか？

• テンポラリの日本語ディレクトリを作成 ( https://github.com/angularjs-jp/angular.js/tree/master/docs/content/tutorial-ja , etc)
• 既存の言語ファイルをコピー、それを上書きする形で各人日本語化を進める
• その間にも日本語のファイルを閲覧できるスクリプトを専任チームが作成、サーバーの準備や翻訳者向けのマニュアルを作成する

ここから、もうちょっと育てていく感じでどうでしょう？

[craftgear]

既存の言語ファイルをコピーするのは各自フォークして、というやりかたでよいでしょうか？

[agektmr]

作業が重複しないように、誰が何をやっているというのをどこかでトラッキングしたいですよね。
良いアイディアはないですか？

[yagishita]

ベタですが、以下はどうでしょうか。

• 翻訳対象の一覧を WiKi に明記する。
• タイトル (xxx: 2013-01-29) というように、どれを誰がいつ手がけたかがわかるようにする。

[agektmr]

全部Issueベースにして細かいルールを決めてもいいんですが、ひとまずそれでいきましょうか。
どなたかソースコード読んで、どうやってドキュメントが生成されているか見てくれる人居ませんかー？ひとまず概要がわかれば十分です。

• nodeのスクリプトを走らせてstaticなhtmlを吐き出す
• nodeのサーバーを立ててダイナミックに表示している

などのレベルでわかっておりません・・・

[agektmr]

ちょっとソースコードを読んでどういう動きになっているのか調べたので、docsを表示するための手順を簡単にまとめてみます。一度しか試してないので、修正が必要な箇所はお知らせ下さい。申し訳ありませんがMacを前提に書きます。

必要なもの

• node (バージョン不明)
• git

ビルド手順 (必要です)

1. まずは git でレポジトリをcloneしてきます

git clone git@github.com:angularjs-jp/angular.js.git

1. できた angular.js ディレクトリに移動し、必要な node モジュールをインストールします

sudo ./init-repo.sh

1. ソースコードをビルドします

rake package

ここまででひと通り環境構築は完了です。次にドキュメントの生成方法です。これは今後翻訳作業を行った後に繰り返し行うものになるはずなので、重要です。(以下は全てangular.jsディレクトリ直下という前提です)

ドキュメントサイト生成手順

1. ソースコードと既存の ngdoc.js を元に静的HTMLファイルを生成するスクリプトを起動します

    ./gen_docs.sh

    Testing, then building documentation...
    ........................................................

    Finished in 0.079 seconds
    56 tests, 93 assertions, 0 failures


    Generating AngularJS Reference Documentation...
    DONE. Generated 211 pages in 4828ms.

1. これで angular.js/build/docs/ 配下に静的なドキュメントサイトのファイルが展開されました。
2. node ウェブサーバーを起動します

    ./nodeserver.sh

1. 下記のURLにアクセスします

    http://localhost:8000/build/docs/tutorial

ドキュメントサイトがローカルのURLで表示されたら成功です。画面上部の Develop から遷移すると本家に移動してしまうので注意して下さい。

[agektmr]

ちなみに上記の手順を踏める自信がないという方は、画面上での表示確認ができないという前提を飲めるであれば、直接.ngdocファイルを編集して頂くことで参加して頂いて構わないと思います。

[agektmr]

今後の進め方

下記のように考えています。

• とにかくみんなで翻訳作業を進める。作業するディレクトリは下記全て。

angular.js/docs/content/

リファレンスについてはこのプロジェクトでは対象外とさせて下さい。

• 予めセクションを区切って担当を割り振り、自由に翻訳をスタート。
• wikiページを用意し、そこで誰が何に取り組んでいるかを分かりやすく掲示。
• 完了した翻訳は PullRequest で監訳に回され、チェックされたものから順に pull される
• 担当範囲の翻訳を終えた人は、空いている区分を新たに担当するか、他の人を手伝う

こんな感じでいかがでしょう？ご意見お待ちしております。

[yogurito]

@agektmr

とにかくみんなで翻訳作業を進める。

賛成です。とにかく始めてみたいです。

wikiページを用意し、そこで誰が何に取り組んでいるかを分かりやすく掲示。

とりあえず、.ngdocファイル単位でおおまかに分担して始められればと思いましたので、分担表を作ってみました。

https://github.com/angularjs-jp/angular.js/wiki/%E5%88%86%E6%8B%85%E8%A1%A8

あとは、どこかのタイミングで用語辞書を作成したほうがやりやすいかもしれませんね。

[agektmr]

@yogurito さんありがとうございます！

Wikiのトップページに作業手順を清書しました。特に異論がなければ皆さん翻訳作業を開始して頂いてよいのではないかと思います！