PyConJP 2011

開催日 8月27日(土) 9:30～18:30 (開場9:00) 場所 産業技術大学院大学 (品川シーサイド駅から徒歩3分)

Subject: reSTudy: STudy group about reST の活動 / An Update on reSTudy Team: team reSTudy

Place: Sub Track (Room 357PC) Ust: http://www.ustream.tv/channel/pyconjp3 Category: non-programmer, documentation, sphinx, docutils

topic: doc time: 16:30-17:00 room: 357PC audience: non-programmer tags: reStructuredText reST sphinx docutils documentation document

Abstruct

reSTructured Text (reST) によるドキュメントサンプルをまとめる活動を行う、reSTudyについて紹介します。

活動の成果などを紹介します。

  • プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
  • 運用ドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
  • reST で blog 書きたい。
  • reST で 論文書きたい。
  • Sphinxドメインっておいしい?
  • Sphinxテーマをカスタマイズするコツは? チュートリアルが欲しい。

reSTudyチーム reSTudy is STudy group about reST

http://groups.google.com/group/restudy/about

講演はreSTudy勉強会主催の波田野が行います。

前振り

  • おまえダレよ
    • 適当に
  • About US
    • reSTudy は、reSTructured Text (reST) によるドキュメントサンプルをまとめる活動をするグループです。
    • 勉強会というより、普及のための知見集約&コンテンツを作るための調査や議論を指向してます。
    • 最近 xxSTudy がはやっているので、ノリで始め & 名付けました。
    • が、目はマジです
  • Why reSTudy?
    • Sphinx イイネ!
    • とりあえず、はじめる。それもわるくはない。
    • しかし、後で知るとガーンとなることも多い。
    • だったら先に知っておきたいことを押えておくのが得策
    • 作り方はわかった、じゃ次は何を作るか、だ。
    • ドキュメントって、必要必要と言う割にテンプレートがばらばら。
    • うまく汎用的なテンプレートがあると嬉しいよね。
    • テンプレートや知見、悩み相談みたいな場が欲しい。
    • よかろう、それが reSTudy だ。

Contents

と夢を膨らませて旗揚げしたが、世の中厳しい

  • かなり漠然としていて暗中模索
  • 業務に追われてて動ける人いない
  • とりあえず意見交換はしてきた

そんな中で世にPushできたものも、ある

  • r_rudi さんの Sphinx 逆引き辞典
  • Shimizukawa さんの一発インストールキット for Windows

今の構想

  • reST 簡易リファレンス
    • チートシート (@shkumagai さん)
  • Step up Sphinx
  • Sphinx life
  • Google Design Doc から考える開発ドキュメントテンプレート reST版
  • 運用作業カタログ (やっている事の見える化)

目指すのは

  • 情報の構造化
  • ワンソースマルチアウトプット
  • 保守工数の低減
  • 考えることに集中できるドキュメント

活動における主なテーマとしては、下記を考えています

  • reST / Sphinx の実践的な使い方、事例の調査・議論、コンテンツ化
  • どこを探したらreST / Sphinxの情報を得られるのかというポインタの集約
  • 関連英語ドキュメントの翻訳、および既存翻訳情報の集約
  • Sphinx 逆引き辞典 充実化への協力

これにより

  • 敷居が下がってユーザが増える。増えれば現場で使えるかも。
  • 利用現場が増えて、reST & Sphinx に対する心理的な拒絶がなくなる。(Excelやめようず)

につながると嬉しいな、と。

Sphinx Users JP との関係

  • Sphinx Users JPは、実装寄り
  • reSTudy は、reST を活用したドキュメンテーションに注目
  • でも、実際には中の人もかなりかぶっていたり、やっていることも近い。
    • Sphinx 関連のものは、Sphinx Users JP の分科会活動として、公式サイトに掲載してもらう方向で相談中。
    • Sphinx に限らないものは、どこか適切な場所に適当に公開という方向かな、と。
  • Sphinx普及の過渡期ということもあり、ゆるく仲良くやっていきます!

summary

  • 仕事でもプライベードでもドキュメントは悩ましい。
  • Sphinx 素敵!
    • 楽で、楽しく、保守しやすいドキュメントの実現へ
  • No Document, No Future. Let’s reSTudy!!