Author: mumumu
Date: Mon Sep 24 19:02:38 2007
New Revision: 1218
Log:
- translated part of "Writing It All Down" Section.
Modified:
trunk/ja/ch04.xml
Modified: trunk/ja/ch04.xml
==============================================================================
--- trunk/ja/ch04.xml (original)
+++ trunk/ja/ch04.xml Mon Sep 24 19:02:38 2007
@@ -1253,6 +1253,7 @@
明らかになってきた事柄を反映させた形で、文書を改訂することができます。
</para>
+<!--
<para>Don't try to be comprehensive. No document can capture
everything people need to know about participating in a project. Many
of the conventions a project evolves remain forever unspoken, never
@@ -1271,7 +1272,31 @@
<emphasis>how</emphasis> to write good code, such as rules about
documenting every API in a certain format, then those guidelines
should be written down as completely as possible.</para>
+-->
+
+<para>
+ 文書を包括的なものにするのはやめましょう。
+ どんな文書でも、プロジェクトに参加するのに必要なことを全て網羅することはできません。
+ プロジェクトで生まれる多くの規約は、ずっと暗黙のもので、
+ 決して明示的に言及されることがないにもかかわらず、
+ メンバー全員がかたくなに守っているものなのです。
+ 単に当り前過ぎるので言及されないものもありますし、
+ 重要だけど曖昧なのでただ避けているだけのものもあります。
+ たとえば、"メーリングリストでは礼儀正しくし、他人を尊重しましょう。
+ また、フレームウォーを始めてはいけません。" とか、
+ "綺麗で、読みやすくバグのないコードを書きましょう。" といったことをガイドラインに書いても意味がありません。
+ もちろん、これらは望ましいことではありますが、
+ これらが望ましくないと思われる世界は存在しないので、言及する価値がないのです。
+ メーリングリスト上で失礼な発言をしたり、バグだらけのコードを書いている人がいたとして、
+ 彼らはプロジェクトのガイドラインにやめろと書いてあるからといってやめはしないでしょう。
+ こういう状況は包括的なガイドラインであらかじめ対処するものではなく、
+ 問題が起きたときに対処すべきものなのです。
+ 一方で、あるフォーマットですべてのAPIを文書化するルールのような
+ よいコードの書き方に関するガイドラインがプロジェクトにある場合は、
+ できる限り完全なものを書いておくべきです。
+</para>
+<!--
<para>A good way to determine what to include is to base the document
on the questions that newcomers ask most often, and on the complaints
experienced developers make most often. This doesn't necessarily mean
@@ -1279,6 +1304,16 @@
coherent narrative structure than FAQs can offer. But it should
follow the same reality-based principle of addressing the issues that
actually arise, rather than those you anticipate might arise.</para>
+-->
+
+<para>
+ ガイドラインに盛りこむ内容を決めるよい方法は、初心者がよく尋ねる質問や、
+ 経験豊富な開発者がよくこぼす不満に関する文書を基にすることです。
+ これは必ずしも FAQ を基にすべきというわけではありません—
+ ガイドラインは、FAQ よりわかりやすい物語風の構造が必要になるでしょうが、
+ FAQ と同じく、将来起こりうる問題よりも、
+ 実際に起こった問題に取り組むという現実的な原則に従うべきです。
+</para>
<para>If the project is a benevolent dictatorship, or has officers
endowed with special powers (president, chair, whatever), then the
_______________________________________________
Producingoss-translators mailing list
[email protected]
http://www.red-bean.com/mailman/listinfo/producingoss-translators
