PHPマニュアルの「導入」を「はじめに」に変えていただいた

変更前 (2017-09-02) 現在
「導入」リンクがある 「はじめに」リンクがある

変更を提案した理由

PHPのモジュールを追加する際、公式サイトのマニュアルを参照してサーバへの導入方法を確認することがよくある。

このとき、誤って「導入」リンクをたどってしまい、モジュールの説明しか確認できずに、がっかりすることもよくあった。

学ばないぼくも悪いのだが、そもそも「導入」なのが混乱の元なのではないだろうか。ためしにTwitterで検索してみると、同様の意見が見つかった。

ツイートにあるとおり、「導入」は「Introduction」の訳語だから、誤訳というわけではない。ただ、「サーバへの導入」という表現が日本語にはあるので、ほかの訳語をあてるのが適切だと考えた。


提案の流れ

とはいえ、ぼくの独断でマニュアルの表現を変えるわけにはいかない。「マニュアルについて」→「ドキュメントの改善を手助けするには」→「PHP Manual Contribution Guide」→「Joining the team」と読み進め、そこで推奨されているように、まずはメーリングリストで相談することにした。投稿したのが下記のメールだ。

2日ほど待ったが、とくにレスポンスはなかった。このときどう考えるかは人によるだろうが、ぼくは「反対者がいないのでチャンスだ」と受け止めた。パッチを作れば取り込んでもらえるかもしれない。


パッチ作成の準備

パッチを作るには、ソースファイルの変更箇所を理解する必要がある。また、変更後のマニュアルを実際に眺めてみて、違和感がないかどうかも確認すべきだ。

まずやるべきことは、ビルドツール・PhDの入手である。参考にしたのは、mumumuさんの「PHP manual generate HOWTO (version 2013-06-29)」だった。

試行錯誤の結果、ぼくの環境では下記のコマンドでPhDがインストールできた。

$ sudo yum install php-xml
$ sudo pear install doc.php.net/PhD doc.php.net/PhD_PHP doc.php.net/PhD_PEAR doc.php.net/PhD_IDE-1.1.1

続いて、ソースファイルを取得する。

$ svn co http://svn.php.net/repository/phpdoc/modules/doc-ja

変更箇所を理解するため、ソースをgrepする。

$ grep -rn '>導入' ./

「導入」を「はじめに」に変更後、ビルドしてみる。

$ php doc-base/configure.php --with-lang=ja --enable-xml-details
$ phd -d doc-base/.manual.xml -f xhtml -P PHP

ビルドされたマニュアルを確認し、違和感のないことが確認できた。


パッチの作成

ここまでくれば、オンラインのドキュメントエディタでパッチが作れる。ローカルで試したのと同じ要領でファイルを編集し、パッチを作った。

その後、メーリングリストにパッチのレビュー依頼メールを投稿した。


公式マニュアルへの適用

ほどなく、前述のmumumuさんから、svnにコミットした旨のリプライがあった。(ありがとうございます!)

そして本日、公式サイトのマニュアルに変更点が適用された。ちなみにこのマニュアルは毎日13時ごろ(日本時間)に更新されているようだ。


以上のような次第で、混乱せずにPHPマニュアルが読めるようになった。

余談だが、今回の件を通じて、未翻訳のファイルが3000以上あることを知った。今後はそちらの翻訳にも挑戦してみたい。

YAGNIでいいと思った

下記の記事がおもしろかった。おもしろかったんだけど、ちょっと疑問がある。

値引き条件などというものは、ビジネス上の都合により変更されやすいものです。このケースのように注文数量だけで値引き可否が決まるというケースもあるかもしれませんが、発注金額も考慮し、あるいは発注者が上得意かどうかも判断要素に含める、というように変更されるかもしれません。一方で、注文数量・金額・発注者が誰かなども含む受注内容に応じて値引き可否が決まる、という点はたぶん変わらないだろうと考えられます。

PHP Mentors -> 「現場で役立つシステム設計の原則」批判 (1) 〜何のために、「データとロジックを一体に」するのか?〜

うーん。「たぶん変わらないだろう」という楽観にもとづいている点で、批判対象の設計と同じ穴の狢のように見えるんだよなあ。

たとえば、「前回の発注に製品Aが含まれ、かつ、今回の発注に製品Bが含まれる場合、値引き可とする」という条件が追加される可能性だってあるだろうし。


かくいうぼくは、「値引きは数量のみに基づいて行われる」というビジネス要件だったら、まず下記のように書く。要件が変わったら、設計を見直す。起こるかどうか分からないことを考えるより、さくっと書いてリリースするのが、ビジネス的にもメンタル的にも吉なのでは。

class DiscountJudge
  def initialize(discount_criteria)
    @discount_criteria = discount_criteria
  end

  def discountable?(quantity)
    quantity >= @discount_criteria
  end
end

class AmountCalculator
  def initialize(discount_rate)
    @discount_rate = discount_rate
  end

  def discount(unit_price, quantity)
    unit_price * quantity * (1 - @discount_rate)
  end

  def amount(discount_judge, unit_price, quantity)
    if discount_judge.discountable?(quantity)
      self.discount(unit_price, quantity)
    else
      unit_price * quantity
    end
  end
end

discount_criteria = 5
discount_judge = DiscountJudge.new(discount_criteria)

discount_rate = 0.2
amount_calculator = AmountCalculator.new(discount_rate)

unit_price = 100
quantity = 6
amount_calculator.amount(discount_judge, unit_price, quantity)
記事検索
Twitter