Re: where is a preferable place of -doc|www contents.

[Taketoshi Sano <xlj06203@xxxxxxxxxxx>]

佐野です。

In article <14156.378.653807.68187Y@xxxxxxxxxxxxxxxxxxxxxxx>
 Mitsuru Oka <oka@debian.or.jp> writes:

> 岡＠奈良先端です。

こんばんは。

> # ということなのでこちらに。

ありがとうございます。

> `Debian JP' が固有名詞なら2番目、`Debian JP Project' が固有
> 名詞なら3番目が自然ですね。僕は既に Debian JP Documentation
> Project って書いてたりしますが。

以前、どこかに "JDDP" と書いてあったような気が。

 Documents/index.html および Documents/index.ja.html のヘッダの
ところにありませんか ?

# 手元にある内容が古いのかな。この辺は CVS で取れるほうが嬉しい。

> 佐野> なんですが、この "Bugs.old", "en" というのは使われていますか ?
> 佐野> もう実体が無いのなら、消してしまっても良い ?
> 
> かも。
> .old を残すまでもなく、過去のものは CVS に残ってる筈だし。

鵜飼さんからのメールによれば CVS 管理以前のものらしいので、
「過去のものが残ってる」ことは無さそうですが、いずれにしろ
既に実体は無いようですし、これら削除については合意が取れたと
みなします。

引用が前後しますが

> 文書の置き場は Documents 以下でいいと思いますが、Project 内
> での作業のための情報は、devel/doc の下でいいと思ってます。
> # devel な用件のうち doc 管轄だと。

> 佐野> 既に devel/doc として作成してしまわれたようですが、www.debian.org を
> 佐野> 見るとすくなくとも /doc は /devel と独立した場所にあります。
> 
> doc/ と devel/ を独立させる事自体には反対しませんが(devel,
> doc, www が独立になるって事ですよね)、

そのとおりです。 /devel, /doc, /www はそれぞれ独立にしたほうが
わかりやすいと思います。

# もし「一緒にする」なら /devel の直下に全部混ぜて置いたほうが、
# /devel/doc や /devel/www などを掘るよりも、スッキリしている
# ように思います。が、もしそれぞれを別に管理するのなら、
# 独立させたほうが良いでしょう。

> 佐野> それから、"Documentations.html", "JPdoc", "Documents" といった
> 佐野> 感じで Document 関係がバラバラなのは何か理由がありますか ?
> 佐野> 内容を見ると、"Documentations.html" は 1.3.1 (bo) の頃の資料の
> 佐野> ようだし、それより更に古いものがありそう。
> 
> 佐野> このあたり、必要なファイルは全部まとめて Documents/ 以下に置き、
> 佐野> doc リポジトリで CVS 管理、というのでは何か不都合がありますか ?
> 
> パッケージになっていないドキュメントについては、僕もそう考え
> ています。パッケージになっているものは、一考を要しますが
> (cvs-buildpackage の活用を考えて)。

> 佐野>  www.debian.or.jp についても /Documents というディレクトリが既に
> 佐野> あって、トップページの「Debian/Debian JP ドキュメント」からは
> 佐野>  Documents/index.ja.html (or index.html for English) にリンクが
> 佐野> 張られていること、最近の資料はみんな Documents 以下にまとまって
> 佐野> いること、などを考えると devel の下に doc や www を作ることが
> 佐野> 得策だとは思いません。 doc は Documents 以下にまとめるほうが
> 佐野> 良いと思います。
> 
> 先にも書いたように、文書の集まりとしての Documents/ に、doc
> project の情報掲示のためのコンテンツを置くのはややこしいです。
> Debian ユーザにとって、Documents 以下に Project 内部の情報が
> あっても邪魔なだけだと思います。
> 
> おっしゃるように、既に -doc な内容がこちらに入っていますが、
> 「Debianを使う上で参照するドキュメント」と「Debian JP
> Projectの活動上で必要なドキュメント」とは、明確に分離してお
> いた方がいいんじゃないかと思います。

「ユーザマニュアル」と「開発者向けマニュアル」を分けよう、と
いう主張ですか ? それにはあまり賛成しませんが、とりあえず今回の件とは
別に doc ML で議論したほうが良さそう。

ここ (www ML) での今回の件は「Debian JP Web Site の CVS リポジトリ
である master.debian.or.jp/var/cvs の整理」という点に絞りたいので。

ただ、現状の Documents/index(.ja).html や Documents/detail(.ja).html は
「見せ方」の点でもっと工夫があっていいんじゃないかな、という気がします。

現状だと「JP オリジナル」の文書にも「日本語翻訳版」というタイトルが
付いていて、おかしな気がするし、「リリースノート」と「インストール
マニュアル」が分離していて、それぞれまとまっているのは「リリース別」
にまとめたほうがユーザーにはわかりやすいだろうし。

全体に「過去の (obsolete な) 文書」と「最近の (effective な) 文書」が
混在していて、わかりにくい気がします。

あああ、このへんは doc ML にしよう、と書きながら意見を主張してますね。
ごめんなさい。続けるなら doc ML に振ってください。

すくなくとも同じ種類 (ユーザ向けあるいは開発者向け、という分類で) の
「文書の集まり」を歴史的な経緯でもってあちこちに分散させるのはやめに
しよう、という点では意見が一致しているものと考えます。

> 佐野> # ついでに index.html, index.ja.html, detail.html, detail.ja.html も
> 佐野> # サブディレクトリを掘って収めると、Web ページだけ CVS 経由でサクっと
> 佐野> # 変更したい場合には都合が良いです。
> 
> cvs/doc 内にて http://*/doc を管理できればいいですね。

はい。まあ account もらったんで自分は今後いつでも「実力行使」できますが
今までは Web から見えるページの「あそこを修正したい」と思っても、権限が
無くてやれなかった (ので齒痒い思いをした) ということがあったものですから。

> 佐野> けっこうあちこちファイルが移動すると思うんで、リンク関係の更新が
> 佐野> 大変かな、という気はします。不要なファイルを削除する、あるいは
> 佐野>  /obsolete なディレクトリ (当然 CVS 管理外) を掘って一箇所に集める
> 佐野> とかだけなら、そんなに問題は無いでしょうけれど。
> 
> 佐野> せっかくの CVS 管理なので、この際ブランチ立ててやる、という手も
> 佐野> ありますが、どうしましょうか ?
> 
> CVS を使っているが故にかえって苦しんでるのが、何か矛盾してま
> すよねぇ...。# rename とか move できないのが痛い。

あらためて見てみると、JPdoc/ 以下の文書は既に Documents/detail.html など
からはリンクされていないみたいですね。そうすると、これも単に obsolete/ 
以下に移動すれば良いだけなのかな。

> 佐野> # 時間と分担を決めて、「せーの」で一斉に更新する、という人海戦術も
> 佐野> # 方法としてはあるかもしれませんが。

とりあえず、現在 master.debian.or.jp/var/www 以下にあるディレクトリ
およびファイルのうち、 www.debian.or.jp のリポジトリで CVS 管理されて
いないものについて

 1) Bugs.old, en は削除

 2) debian.org, debian.org-local は ./obsolete/ (新設) へ移動

 3) Documentations.html, JPdoc も同様に ./obsolete/ (新設) へ移動

というところまでは、すぐにできそうですね。これは単に「いつやるか」
を決めるだけで良さそうです。

それから

 4) ./www を作成して
 4-1) WebMasters.html, WebTranslations.html をそこへ移動
 4-2) Todo.html{.ja,.en} のリンクを修正

も、それほど時間のかかる作業では無さそうです。ミラーの合間を
狙ってやれば、充分でしょう。

あと、これ以降はまだ合意が取れていませんが

 5) ./devel/doc を ./doc に移動して
 5-1) Description-ja.html を ./doc に移動
 5-2) Todo.html{.ja,.en} のリンクを修正

も、これだけやるならミラーの合間で充分でしょう。

 5-3) ./Documents/ 以下の
    index.html, index.ja.html, detail.html, detail.ja.html を
      ./doc 以下に移動してリンクを修正

これが結構時間かかりそう。どうせなら index や detail での「見せ方」も
考えたほうが良いだろうから、これはもっと doc ML で議論した後のほうが
良いでしょうね。

> ちょこっとだけ反応してみました。
> 力尽きてきた(*)のでこの辺で...。
> 
> (*) この前の親不知抜歯が予想以上に体力を消耗。

お大事に。

とりあえず、すぐ実現できそうなところは見えたので、そこから
ボチボチ手をつけていきます。

-- 
  Taketoshi Sano: <kgh12351@xxxxxxxxxxx>