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

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

[kurap]

とりまとめていただいてありがとうございます。
担当箇所はやりたいところから着手するかんじでいいでしょうか？

[agektmr]

日本語でメールの返信しちゃうと文字化けちゃうのですね・・・
担当箇所の件ですが、早い者勝ちで好きなところからやっちゃってよいと思います！

[iseki-masaya]

はじめまして。isekiです。
小さな箇所ですが、翻訳したのでプルリクエストを送りました。
githubは初めてなので、「使い方間違ってるよ」ってところがあったら指摘していただけると幸いです。

[thayashi]

林です。まだ取り掛かっていませんが、まずはtutorialのstep01までを担当としました。

[iseki-masaya]

content-jaディレクトリを作成し、そこに翻訳したHTMLファイルを入れておきました。
build/以下をコピーしただけなので、英語表記のHTMLやcss,jsも入っています。
なので、http://localhost:8000/content-ja/docs/tutorialでアクセスすれば、和訳されたページをレイアウトを保持したまま見ることができます。また、原文を見たい場合はhttp://localhost:8000/build/docs/tutorialで今まで通りアクセスできます。

翻訳したら、content-ja以下の対応するHTMLファイルと入れ替えるという具合に進めて行けたらと考えています。

[agektmr]

@iseki-masaya #3 (comment) の方にコメントしちゃいました。

[iseki-masaya]

よく調べずに、勝手に判断していました。
すみません。

一応、HTMLファイルを積極的に上げる理由は2つありました。
ひとつは、監訳する際にHTMLファイルの方が簡単かなと思ったからです。
もうひとつは、日本語の.ngdocファイルをbuildさせるのにスクリプトを書き直さないといけないと思ったからです。
しかし、2つともそれほど問題ではないことが分かりました。
一つ目に関しては、訳の確認をしたあとに.ngdocファイルを編集しなければならないので、むしろHTMLファイルで監訳した方が大変なことに気が付きました。
二つ目に関しては、スクリプトの変更箇所が多いと思っていたのですが、reader.jsの39行目のpath2のdocs/contentを変更するだけで良かったので、全く問題ありませんでした。

なので、.ngdocファイルだけcommitする方法で良い思います。

[agektmr]

@iseki-masaya さん
翻訳の進め方についてはまだ定まっていない段階です。現時点では、色々な方法を検討した上で、よりよいものを選択していくやり方がよいのではないかと思っています。今回はひとつの選択肢を示し、よりよい方法があると確認できたという意味で、結果的に成功だったと思います。今後もどんどんやり方を提案してくださると助かります。

スピードが出ないのでご迷惑をおかけするかもしれませんが、今しばらくお付き合い下さい。

[agektmr]

もうひとつご相談です。せっかくcontent-jaというディレクトリを作って頂いたのですが、当初は既存のcontentでファイルを直接編集してしまうことを想定していました。利点としてはdiffを見ながら監訳できる、buildスクリプトをいじらなくてよい、などです。
content-jaを作った方が作業が捗るという方は、理由を教えて頂けないでしょうか？

[iseki-masaya]

content-jaを作った理由は、原文を残しておかないと監訳の作業ができないと思ったからです。
しかし、そもそも原文はAngularJSの本家(http://angularjs.org/#)にあるので、あえてcontent-jaを作成する理由はないですね。
強いていうのなら、ローカルのみで監訳できることですかね。