技術部の今岡です。

もう少し前のことになってしまって恐縮ですが、ドキュメント勉強会というものに参加してきました。

8月6日（木）　大阪市北区のメビック扇町というところで、場所はCakePHP関西勉強会の会場と同じところです。

そのCakePHP関西勉強会の第二回が、私の技術系勉強会の初体験だったにもかかわらず、今回の勉強会では発表者に名前を連ねることになってしまいました。

CakePHP勉強会の後、人から薦められてアカウントを作っていたTwitterを本格的に利用し始めました。

Twitterでは様々な人が好き勝手なことを雑多に呟き、その呟きに興味があったりして継続的にその呟きを読む為には、呟いている人を「フォローする」という操作を行います。

Twitterの詳しい話は今回の話題ではないですが、そのTwitter上でCakePHP勉強会を主催された新原さんという方をフォローさせて戴きました。

新原さんがTwitter上で勉強会というものについて、とか、ドキュメント勉強会ってどう思う？というような疑問を投げられまして、私を含め数人がそれに反応し、その反応の内容を受けて新原さんはドキュメント勉強会を開催しようと決定されました。

（新原さん自身のブログやWassarという別のサービスなどもありますので、Twitterがすべてではないと思います。念のため。）

勉強会の決定や開催日時の告知にもTwitteｒが有効に活用されました。

そして、そのTwitterを通じて、私のところに発表の依頼が飛んできたのでした・・・。

業界で使われている技術は沢山あり、日々新しくなったり廃れたりしています。

その技術に関しての勉強会は今までもいろいろと開催されているのですが、その技術を伝達したり技術を使った仕事の依頼、記録などに使われる書類(＝ドキュメント）の書式は、業界標準が存在しません。

大手企業だとしっかりした社内基準がありますが、個人や零細のソフトハウスでは基準はなく、ドキュメントの存在さえ怪しいのが現状だと思います。

ですので、必要という意識さえないという人から、書こうにも書き方が判らない人、常にドキュメント作成を専門にやりまくっているという人まで同じ業界でもいろんな人がいることと思います。

今回は、ドキュメント作成に興味があったり、なんらかの不自由感困った感がある人達で集まって、それぞれがどんな風にドキュメントを作っているのか、何に困っているのかを話し合ってみましょう！という、チャレンジっぽい勉強会です。

主催者の新原さんから、お題が出ました。それは

「Poken販売サイト」

Pokenというのは、名刺代わりになるマスコットのようなおもちゃのようなモノです。かわいいです。

世間の一部で愛好されていて、新原さんもお持ちです。

それを販売するサイトの製作にあたり、必要と思われるドキュメントを発表担当者がそれぞれに作って勉強会当日にそれを公開し話のタネにします。

勉強会の運営と発表者の連絡用に、事前にメーリング・リストが開設され、出欠確認・お題の発表・新原さんのサンプルドキュメントの配布・当日の会場到着予定時間のお知らせなどに活用されました。

細かい話ですが、勉強会までの道のりは下記のような感じです。

7月7日　ドキュメント勉強会の開催決定

7月15日　今岡のところに発表の依頼がくる

7月下旬　サンプルドキュメントの配布

8月6日　勉強会の開催

勉強会の実際

さて、では実際の勉強会とはどんな感じだったのでしょうか？

すでに参加された皆さんが自身のブログなどにいろいろ書いておられますが、とっても面白く為になる内容でした。

いや、本当。

事前に打ち合わせしてないことが信じられないくらい、各発表者の製作意図や方法がバラバラで、結果的に非常にバラエティに富んだ発表内容となりました。

私は自身の日常業務そのままに、小さなソフトハウスが下請けでシステムを製造するという前提でいくつかのドキュメントを作りました。内容としては下記になります。

・メニューフロー

・データベース設計書

・フォルダ構成

・スケジュール

・その他前提条件などのメモ

ドキュメントを書くにあたり使用したのはExcelです。

特に笑いどころのない生真面目なものを作成してしまいました。

内容に興味のある方はご一報ください。

発表で使用したドキュメント類はどれでもお送りさせて戴きます。

ダウンロードの仕掛けが出来てなくてすいません・・・。

お題である通販サイトの製作には、製造部隊のみならずプロデューサに当たる方やデザイン担当の方などいろいろな人が関わることになります。もちろん、依頼主である顧客もいますし、サイトを利用しPokenを購入するお客様もおられます。

誰の立場でドキュメントを書くかで、書き方も内容も全然違ったものになります。

私は掴みの新原さんの後、二番目の発表でしたが、その後にはWEBプロデューサの方、はたまたドキュメントを普段まったく書かないという方の発表が続き、途中Poken販売サイトというお題にまったく触れない果敢な発表もあり、聞きなれない強力なドキュメント製造ツールのお話、最後に大手さんだ！！と感動の超きっちりのドキュメントが公開されました。

途中で休憩があり、みたらしだんごを戴きました。

ひとりの発表持ち時間は10分が目安とのお話だったのですが、やはり熱くなりがちで時間は押し押しでした。

もっといろんなドキュメントがあるはずですし、もっとしたい質問もあるのでは？と思いました。

第二回の開催が待たれます。

時間の関係で質疑応答はあまりなかったのですが、多くの方が懇親会に参加されましたので、そこで少しは補足が出来たのかなと思います。

私の周辺ではPokenとiPhoneの話題がもっぱらでしたが・・・。

MacにもiPhoneにも馴染みがない私は、隣の席の方に「夏ライオン」のアイコンを見せてもらって感動しました。

さて、つらつらとあまり内容はない記事ではありますが、勉強会の雰囲気が伝われば幸いです。

皆さん、勉強会にどんどん参加しましょう！

出来ればがんがん発表しましょう！！

勉強会の敷居は低いです。

業界人と業界の周辺の方、ウェルカムです。

と、言うようなことを主催者の新原さんがおっしゃってました。・・・と、思います・・・。

<?php
/**
 * CSV class
 *
 * Licensed under The MIT License
 * Redistributions of files must retain the above copyright notice.
 *
 * @author Siegfried Hirsch <siegfried.hirsch@gmail.com>
 * @copyright Copyright 2008-2009, Siegfried Hirsch
 * @license http://www.opensource.org/licenses/mit-license.php The MIT License
 * @created Januar 21, 2009
 * @version 1.0
 **/
class CsvSource extends DataSource {

/**
 * Description string for this Data Source.
 *
 * @var unknown_type
 */
    var $description = "CSV Data Source";
    var $delimiter = ';';                     // delimiter between the columns
    var $maxCol = 0;
    var $fields = null;                     // fieldnames
    var $handle = false;                     // handle of the open csv file
    var $page = 1;                             // start always on the first page
    var $limit = 99999;                     // just to make the chunks not too big

/**
 * Default configuration.
 *
 * @var unknown_type
 */
    var $__baseConfig = array(
            'datasource' => 'csv',
            'path' => '.',                     // local path on the server relative to WWW_ROOT
            'extension' => 'csv',             // file extension of CSV Files
            'readonly' => true,             // only for reading
            'recursive' => false,             // only false is supported at the moment
            );


/**
 * Constructor
 */
    function __construct( $config = null, $autoConnect = true ){

        // Configure::write('debug', 1);
        $this->debug = Configure::read( 'debug' ) > 0;
        $this->fullDebug = Configure::read( 'debug' ) > 1;

        // debug($config);
        parent::__construct( $config );

        if( $autoConnect ){
            return $this->connect();
        } else {
            return true;
        }

    }


/**
 * Connects to the mailbox using options in the given configuration array.
 *
 * @return boolean True if the mailbox could be connected, else false
 */
    function connect() {

        $config = $this->config;
        $this->connected = false;

        uses( 'Folder' );

        if( $config['readonly'] ){
            $create = false;
            $mode = 0;
        } else {
            $create = true;
            $mode = 0777;
        }

        //$config['path'] = WWW_ROOT . $config['path'];
        $config['path'] = TMP . $config['path'];        // Added by Imaoka on 26-Jun-2009

        // debug($config['path']);
        $this->connection = &new Folder( $path = $config['path'], $create, $mode );
        if( $this->connection ){
            $this->handle = false;
            $this->connected = true;
        }

        return $this->connected;
    }


    /**
     * listSources
     *
     * @author: SHirsch
     * @created: 21.01.2009
     * @return array of available CSV files
     */
    function listSources() {

        $config = $this->config;

        if( $this->_sources !== null ){
            return $this->_sources;
        }

        if( $config['recursive'] ){
            // not supported yet -> has to use Folder::findRecursive()
        } else {
            // すべてにCSVファイル名を取得し、拡張子を省いてテーブル名にしたものを$listに格納する
            // list all .csv files and remove the extension to get only "tablenames"
            $list = $this->connection->find( '.*' . $config['extension'], false );
            foreach( $list as &$l ){
                if( stripos( $l,  '.' . $config['extension'] ) > 0 ){
                    $l = str_ireplace( '.' . $config['extension'], '', $l );
                }
            }
            $this->_sources = $list;
        }

        //debug( $list );

        return $list;
    }


/**
 * Convenience method for DboSource::listSources().  Returns source names in lowercase.
 *
 * @return array
 */
    function sources( $reset = false ){

        if( $reset === true ){
            $this->_sources = null;
        }

        return array_map( 'strtolower', $this->listSources() );
    }


/**
 * Returns a Model description (metadata) or null if none found.
 * デリミッタ、列数、各列名をセット。各列名を返す。
 *
 * @return mixed
 **/
    function describe( $model ){

        //debug( $model->table );
        $this->__getDescriptionFromFirstLine( $model );

        //debug( $this->fields );
        return $this->fields;
    }


    /**
     * __getDescriptionFromFirstLine and store into class variables
     *
     * @author: SHirsch
     * @created: 21.01.2009
     *
     * @param $model
     * @set CsvSource::fields array with fieldnames from the first line
     * @set CsvSource::delimiter char the delimiter of this CSV file
     *
     * @return true
     */
    private function __getDescriptionFromFirstLine( $model ){

        $config = $this->config;

        //$config['path'] = WWW_ROOT . $config['path'];        // Added by Imaoka on 26-Jun-2009
        $config['path'] = TMP . $config['path'];            // Modified by Imaoka on 26-Jun-2009

        $filename = $model->table . "." . $config['extension'];
        $handle = fopen( $config['path'] . DS .  $filename, "r" );

        $line = rtrim( fgets( $handle ) );     // remove \n\r
        $data_comma = explode( ",", $line );
        $data_semicolon = explode( ";", $line );

        if( count( $data_comma ) > count( $data_semicolon ) ){
            $this->delimiter = ',';
            $this->fields = $data_comma;
            $this->maxCol = count( $data_comma );
        } else {
            $this->delimiter = ";";
            $this->fields = $data_semicolon;
            $this->maxCol = count( $data_semicolon );
        }

        fclose( $handle );

        return true;
    }


    /* close
    **
    ** @created: 21.01.2009 14:59:08
    **
    */
    function close(){

        if( $this->connected ){
            if( $this->handle ){
                @fclose( $this->handle );
                $this->handle = false;
            }
            $this->connected = false;
        }
    }


/**
 * The "R" in CRUD
 *
 * @param Model $model
 * @param array $queryData
 * @param integer $recursive Number of levels of association
 * @return unknown
 */
    function read( &$model, $queryData = array(), $recursive = null ){

        $config = $this->config;

        //$config['path'] = WWW_ROOT . $config['path'];        // Added by Imaoka on 26-Jun-2009
        $config['path'] = TMP . $config['path'];            // Modified by Imaoka on 26-Jun-2009

        // デリミッタ、列情報の取得
        $this->fields = $this->describe( $model );            // Added by Imaoka on 26-Jun-2009

        $filename = $config['path'] . DS . $model->table . "." . $config['extension'];

        if( $this->handle === false ){
            $this->handle = fopen( $filename,  "r" );
        }

        $queryData = $this->__scrubQueryData( $queryData );

        // get the limit
        if( isset( $queryData['limit'] ) && !empty( $queryData['limit'] ) ){
            $this->limit = $queryData['limit'];
            //debug( $this->limit );
        }

        // get the page#
        if( isset( $queryData['page'] ) && !empty( $queryData['page'] ) ){
            $this->page = $queryData['page'];
            //debug( $this->page );
        }

        if( empty( $queryData['fields'] ) ){
            $fields = $this->fields;
            $allFields = true;
        } else {
            $fields = $queryData['fields'];
            $allFields = false;
            $_fieldIndex = array();
            $index = 0;

            // generate an index array of all wanted fields
            foreach( $this->fields as $field ){
                if( in_array( $field, $fields ) ){
                    $_fieldIndex[] = $index;
                }
                $index++;
            }
        }

        $lineCount = 0;
        $recordCount = 0;
        $resultSet = array();

        // Daten werden aus der Datei in ein Array $data gelesen
        // Modified by Imaoka on 26-Jun-2009
        //while( ( $data = fgetcsv( $this->handle, 8192, $this->delimiter ) ) !== FALSE ){
        while( ( $data = fgetcsv_reg( $this->handle, 8192, $this->delimiter ) ) !== FALSE ){
            if( $lineCount == 0 ) {
                // throw away the first line
                $lineCount++;
                continue;
                // $_page = 1;
            } else {
                // compute the virtual pagenumber
                // Modified by Imaoka on 26-Jun-2009
                //$_page = floor( $lineCount / $this->limit ) + 1;
                $_page = floor( $lineCount / $this->limit );
                if( $lineCount % $this->limit > 0 )
                    $_page++;

                // do have have reached our requested page ?
                if( $this->page > $_page ){
                    $lineCount++;
                    continue;
                }
                // skip over records, that are not complete
                if( count( $data ) < $this->maxCol ){
                    $lineCount++;
                    continue;
                }

                $record = array();
                if( $allFields ){
                    $i = 0;
                    $record['id'] = $lineCount;
                    foreach( $fields as $field ){
                        $record[$field] = $data[$i++];
                    }
                    $resultSet[] = $record;
                } else {
                    $record['id'] = $lineCount;
                    if( count( $_fieldIndex ) > 0 ){
                        foreach( $_fieldIndex as $i ){
                            $record[$this->fields[$i]] = $data[$i];
                        }
                    }
                    $resultSet[] = $record;
                }
                unset( $record );

                // now count every record
                $recordCount++;
                $lineCount++;

                // is our page filled with records, then stop
                if( $recordCount >= $this->limit ){
                    break;
                }
            }
        }
        $result[$model->table] = $resultSet;
        return $result;
    }

/**
 * Private helper method to remove query metadata in given data array.
 *
 * @param array $data
 * @return array
 */
    function __scrubQueryData( $data ) {

        foreach( array( 'conditions', 'fields', 'joins', 'order', 'limit', 'offset', 'group') as $key ){
            if( !isset( $data[$key] ) || empty( $data[$key] ) ){
                $data[$key] = array();
            }
        }
        return $data;
    }

}
?>

    var $csv = array(
        'datasource' => 'csv',
        'path' => 'csv',                 // local path on the server
        'extension' => 'csv',             // file extension of CSV Files
        'readonly' => true,             // only for reading
        'recursive' => false,             // only false is supported at the moment
        );

<?php 
class Price extends AppModel {
    var $name = 'Price';
    var $useDbConfig = 'csv';
    var $useTable = false;
}
?>

<?php
class PricesController extends AppController
{
    var $name = 'Prices';
    var $uses = array( 'Price' );

    function read(){

           $list = $this->Price->find( 'all' );
           $this->set( 'list', $list['prices'] );
    }
?>

<h2>CSVデータ一覧</h2>
<table>
    <tr>
        <th>ID</th>
        <th>名前</th>
        <th>部署・役職</th>
        <th>通勤手段</th>
        <th>好きなもの</th>
        <th>価格</th>
    </tr>
<?php

    foreach( $list as $data )
        {
        print <<<EOD
    <tr>
        <td>{$data['id']}</td>
        <td>{$data['name']}</td>
        <td>{$data['dep']}</td>
        <td>{$data['device']}</td>
        <td>{$data['favourite']}</td>
        <td>{$data['price']}</td>
    </tr>
EOD;
        }
?>
</table>

 $list = $this->Price->find( 'all', array(    'limit' => 4,     // read only 100 records
　　                                                    'page' => 1,    // start at page 2, limit is needed to make sense
    　　                                                'fields' => array( 'id', 'name', 'price' )
                                                )
                            );