Welcome to reSTudy
tcsh
reSTudy は、reSTructured Text (reST) によるドキュメントサンプルをまとめる活動をするグループです。
勉強会というより、普及のための知見集約&コンテンツを作るための調査や議論を指向してます。
活動における主なテーマとしては、下記を考えています。
- reST / Sphinx の実践的な使い方、事例の調査・議論、コンテンツ化
- Sphinx 逆引き辞典 充実化への協力
http://sphinx-users.jp/reverse-dict/index.html
と書くと硬い印象があるかもですが、個人的には、
- プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
- 運用ドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
- Sphinxドメインっておいしい?
- テーマをカスタマイズするコツは? チュートリアルが欲しい。
- reST で blog 書きたい。
- reST で 論文書きたい。
- reST で 週報書きたい。
などなど、とりとめもなく野望があります。
これが
- 敷居が下がってユーザが増える。
- 利用現場が増えて、reST & Sphinx に対する心理的な拒絶がなくなる。(Excelやめようず)
につながると嬉しいな、と。
Google Groups でのディスカッションはオープンとし、会議については参加者全員が
なにか疑問や成果を持ち合う場にしたいと考えています。
ご意見、コメントお待ちしておりまーす。
Takayuki Shimizukawa
reSTudyに参加しました。よろしくおねがいします。
2011年6月26日10:04 tcsh <tcsh....@gmail.com>:
> reSTudy は、reSTructured Text (reST) によるドキュメントサンプルをまとめる活動をするグループです。
>
> 勉強会というより、普及のための知見集約&コンテンツを作るための調査や議論を指向してます。
知見集約という意味では、どこを探したら情報を得られるのか、といった探し方も押さえておきたいところですね。でも見つかるのは英語ドキュメントが多いでしょうから、そういったものを翻訳して（あるいは翻訳してあるものを探して）どこかに集約するという感じでしょうか。
> - プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
> - 運用ドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
これは欲しいですね！
書式と内容と2重に分からないと、なかなか「使ってみよう」という気にならないですからね・・。
春のOSCでも「ドキュメントテンプレート集が欲しい。製品マニュアル向けや設計書など。」というコメントは頂いてました。
http://sphinx-users.jp/event/20110304_osc_tokyo_spring.html
reST基礎知識と、コンテンツテンプレートのあたりから集める＆作っていきましょう。
あとは「Sphinx-users.jpの分かりにくいところを改善する」提案とかかな。
--
清水川.jp
tcsh
# Subject カスタマイズしてみました。
清水川さん、さっそくありがとうございます。
reST基礎知識と、コンテンツテンプレートと、あと個人的に「そもそもどんなドキュメント」
が必要なの? というあたりが切実だったりするのでこれらを中心にディスカッションできれば
と考えています。
リソースをどう管理していくかは、まだ考えがまとまってないんですが、
1. ディスカッションは、Google Groups をメインでおこなう。
テーマ別にスレッドを切る感じ?
2. ディスカッションを元に、テーマを決めてreSTudy meetingを開催。
基本的には、コンテンツビルド相談 + 悩み相談 で、参加者は全員なにかネタをもってくる。
3. コンテンツは reST で記述し、Mercurial をつかった分散バージョン管理下に置きたい。
(マスターは、BitBucket に置く、みたいな感じ。)
コンテンツから clone したものは自由改変OK。逆に自由改変がNGなものはコンテンツには
置かない。
4. Sphinx と密接に関わる部分は Sphinx-user-jp と密接に連携し、そうでない部分について
は適切な公開方法を適当に考える。
というあたりをざっくり考えています。
ここでの議論を元にオレオレコンテンツとして練りあげたり、独自に仕事に活かすこともOKだと
考えています。
まずは、Google Groups での議論からはじめたいですが、適当にスレッドを切りはじめる、
とかでしょうか。
今晩あたり、個人的にやりたいことのスレッドをいくつかおこしてみたいと思います。
On 6月26日, 午前10:54, Takayuki Shimizukawa <shimizuk...@gmail.com> wrote:
> 清水川です。
> reSTudyに参加しました。よろしくおねがいします。
>
> 2011年6月26日10:04 tcsh <tcsh.csh...@gmail.com>:
>
> > reSTudy は、reSTructured Text (reST) によるドキュメントサンプルをまとめる活動をするグループです。
>
> > 勉強会というより、普及のための知見集約&コンテンツを作るための調査や議論を指向してます。
>
> 知見集約という意味では、どこを探したら情報を得られるのか、といった探し方も押さえておきたいところですね。でも見つかるのは英語ドキュメントが多いでしょう から、そういったものを翻訳して（あるいは翻訳してあるものを探して）どこかに集約するという感じでしょうか。
togakushi
reSTudyに参加してみました。よろしくお願いします。
> 3. コンテンツは reST で記述し、Mercurial をつかった分散バージョン管理下に置きたい。
> (マスターは、BitBucket に置く、みたいな感じ。)
> コンテンツから clone したものは自由改変OK。逆に自由改変がNGなものはコンテンツには
> 置かない。
この部分は Mercurial の使い方がよくわかってない人が困るのでは、、、と思いました。
# 参加者を見る感じだとみんな使えそうですが。
Mercurial の使い方を reST でドキュメント化してあると嬉しいかなと。
公式マニュアルだけでも足りそうですが、グループに特化した使い方や
ルールなどがまとまってると、実際に使ってる例として普及に役立つと思います。
---
togakushi
shimizukawa takayuki
On 2011/06/28, at 7:57, togakushi <nina.to...@gmail.com> wrote:
> Mercurial の使い方を reST でドキュメント化してあると嬉しいかなと。
> 公式マニュアルだけでも足りそうですが、グループに特化した使い方や
> ルールなどがまとまってると、実際に使ってる例として普及に役立つと思います。
以前、最低限必要そうなところを書いたものがあります。
http://sphinx-users.jp/articles/business-document-sample/2portfolio/development/code-repository.html
改めて見ると、初めての人向けとしては足りないですね…
インストールと、実際の利用例を書くべきですかね？
--
清水川
tcsh
あっという間に一ヶ月たっちゃいました。すいませんm(..)m
個人的に
1. プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよ
ね
2. 運用ドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
3. テーマをカスタマイズするコツは? チュートリアルが欲しい。
あたりから手をつけはじめたい気分です。
- Sphinxドメインっておいしい?
- reST で 論文書きたい。
- reST で 週報書きたい。
やりかたですが、テーマ別にGoogle Groupsのディスカッションでスレッド切りつつ、サマリをどこかに
載せる(bitbucket?)のは、いかがでしょうか。
# ページとかファイルが廃止になっちゃったので、不便ですねぇ。
昔のMLさながらですが、下記スレッドの起点メールを投げるかんじでやってみたいと思います。
1. プロダクトドキュメント
2. 運用ドキュメント
3. テーマのカスタマイズ
4. Sphinxドメイン
5. reST で blog
6. reST で 論文
7. off topic
乞うご意見。
Komiya Takeshi
> 1. プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよ
> ね
> 2. 運用ドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
> 3. テーマをカスタマイズするコツは? チュートリアルが欲しい。
>
> あたりから手をつけはじめたい気分です。
3 はともかく、1, 2 って誰かディスカッションできそうですかねー?
僕はプロダクトはやってなかった(正確に言うとやってたけどドキュメントがなかった)し、
運用もたいして触れていないのでどっちもちゃちゃを入れる程度になりそうです。
3 はやったことがないものの、手を出せばできるぐらいの距離感だと思ってます。
1 は代わりに SI 案件のドキュメントという方向もあるのでは。
それであれば僕も協力できます。(それでもうちの会社はあんまり書いてないですが…)
積極的反対ではまったくないのですが、自分の立ち位置を宣言してみます。
> - Sphinxドメインっておいしい?
いまのところクラスリファレンスが書ける程度の機能しかないですよね。
開発系の資料であればともかく、その他のもので使えるかはあやしそうなきがします。
Takayuki Shimizukawa
小宮さんのコメントにほぼ同じなので、差分だけ書きます。
2011年7月25日1:20 Komiya Takeshi <i.tk...@gmail.com>:
>> - Sphinxドメインっておいしい?
>
> いまのところクラスリファレンスが書ける程度の機能しかないですよね。
> 開発系の資料であればともかく、その他のもので使えるかはあやしそうなきがします。
Sphinxドメインは拡張が可能なrole集合と言えるので、例えば「運用」ドメイン
として出力をカスタマイズしたい複数のroleを定義する、なんてことが、拡張
としては比較的簡単に作ることができます。
既存のものについては小宮さんのコメント通り、関数やクラスのハイライトと
クロスリファレンスをしてくれるドメインしか用意されていないので、「おいしい」
ところがあるとすれば上記のように独自ドメインを作ったときじゃないかと
思います。
--
清水川.jp
tcsh
ありがとうございます。
まずは、簡単なものでもいいので、テンプレート集を作りたい
と思っています。
# 以前のメールにあった、OSCでの声に応える、みたいな
# イメージです。
SIer経験が殆どないのでイメージし切れていないのですが
まずは、こんなシート、こんなテンプレあるよね的なブレスト
からできればと思っています。
プロダクトドキュメントについては、要求仕様書、機能要件、
非機能要件、概要設計書、機能一覧、画面設計書、詳細設計書
みたいなものが、あるのかな、と。
(個人的には今、この辺りの知識不足で苦労してたりします。)
運用ドキュメントについては、個人的に作業カタログ(一覧)と
いうものを考えていて、Excel版から移植したいと思っています。
取り急ぎ、こんなイメージです、というあたりを。
皆さんの活動への期待、意欲も伺いたいです。
On 7月25日, 午前8:09, Takayuki Shimizukawa <shimizuk...@gmail.com> wrote:
> 清水川です。
>
> 小宮さんのコメントにほぼ同じなので、差分だけ書きます。
>
Komiya Takeshi
> SIer経験が殆どないのでイメージし切れていないのですが
> まずは、こんなシート、こんなテンプレあるよね的なブレスト
> からできればと思っています。
>
> プロダクトドキュメントについては、要求仕様書、機能要件、
> 非機能要件、概要設計書、機能一覧、画面設計書、詳細設計書
> みたいなものが、あるのかな、と。
> (個人的には今、この辺りの知識不足で苦労してたりします。)
それでいうとプロダクトであげてもらったものとプロダクトは似たようなものですね。
ぱっと思いつくのはデータベース定義、利用マニュアルとかぐらいでしょうか。
その上でどれを作るのか、メンテナンスするのか、ですよね。
うちは小さいプロジェクトだったり、お客さんがドキュメントを要求しないなどのコスト的な理由で、
最低限の小さいドキュメントしかない (もしくは存在しない)状態ですね。
そもそもよく言う「概要設計書」と「詳細設計書」の違いもあんまり分かってないです。
これはどこから手を付けていいのか分からない感じですね。
おそらく清水川さんのドキュメントのポートフォリオ? がベースになるんでしょうね。
http://sphinx-users.jp/articles/business-document-sample/2portfolio/index.html
Komiya Takeshi
>>> - Sphinxドメインっておいしい?
>>
>> いまのところクラスリファレンスが書ける程度の機能しかないですよね。
>> 開発系の資料であればともかく、その他のもので使えるかはあやしそうなきがします。
>
> Sphinxドメインは拡張が可能なrole集合と言えるので、例えば「運用」ドメイン
> として出力をカスタマイズしたい複数のroleを定義する、なんてことが、拡張
> としては比較的簡単に作ることができます。
どういうものを「ドメイン」として定義するのか検討するとよいということですかね。
マークアップの数を増やすと、書き分けされなくなって、
逆に使われなくなるのではないかと懸念してます。
ほとんど :term: でいいんじゃないかという気がするのですが、
積極的にロールを与えたいケースってどんなものですかね。
※ セマンティック度をあげるとたいていの人は音を上げると僕は予想しているので、
よっぽど汎用的なものでなければ用意しない方が使われると思っています。
hokorobi
よろしくお願いします。
> 皆さんの活動への期待、意欲も伺いたいです。
こんなドキュメントを reST で書いたら、こんな感じで良かったよ、
こんな感じでまずかったよという話が聞けると良いなと思っています。
私の場合、ユーザが使うシステムの使用手順書を reST で書いて、
Sphinx で HTML にして説明したときは、なかなか感触が良かったな
という経験があります。
説明をするときは大抵 PowerPoint を使っているのですが、
見目よく手順書ができていて、それをうまいこと説明できればいらないな～とかとか。
（特殊な話のような気もしますが……）
---
hokorobi @h0k0r0bi
Tetsuo Mitsuda
あっ、はじめまして。よろしくおねがいしますです。
> SIer経験が殆どないのでイメージし切れていないのですが
> まずは、こんなシート、こんなテンプレあるよね的なブレスト
> からできればと思っています。
IPAにドキュメントのサンプル集がありますので、このあたり
から材料としてめぼしいものはピックアップ出来るんじゃない
かな、と思います。
http://sec.ipa.go.jp/tool/ep/index.html
要件定義 のページなどそれっぽいものがそろってそうです。
http://sec.ipa.go.jp/tool/ep/ep2.html
では。
2011年7月25日9:04 tcsh <tcsh....@gmail.com>:
--
"Blender rocks!!"
MITSUDA Tetsuo
twitter ID: @lab1092
tcsh
ありがとうございます!
結構ボリュームある一方で、それほど整理されていない印象がありますが、
この中で自分達が使いそうなものをピックアップして、reSTサンプルを
作るのがよさそうですね。
On 7月25日, 午後9:31, Tetsuo Mitsuda <lab1...@gmail.com> wrote:
> 三津田です。
> あっ、はじめまして。よろしくおねがいしますです。
>
> > SIer経験が殆どないのでイメージし切れていないのですが
> > まずは、こんなシート、こんなテンプレあるよね的なブレスト
> > からできればと思っています。
>
> IPAにドキュメントのサンプル集がありますので、このあたり
> から材料としてめぼしいものはピックアップ出来るんじゃない
> かな、と思います。http://sec.ipa.go.jp/tool/ep/index.html
>
> 要件定義 のページなどそれっぽいものがそろってそうです。http://sec.ipa.go.jp/tool/ep/ep2.html
>
> では。
>
tcsh
On 7月25日, 午後12:35, hokorobi <hokorobi.hokor...@gmail.com> wrote:
> こんなドキュメントを reST で書いたら、こんな感じで良かったよ、
> こんな感じでまずかったよという話が聞けると良いなと思っています。
>
> 私の場合、ユーザが使うシステムの使用手順書を reST で書いて、
> Sphinx で HTML にして説明したときは、なかなか感触が良かったな
> という経験があります。
感触が良かった点をもちょっと具体的にお聞きしたいです。
> 説明をするときは大抵 PowerPoint を使っているのですが、
> 見目よく手順書ができていて、それをうまいこと説明できればいらないな～とかとか。
> （特殊な話のような気もしますが……）
# pptは構造的に書かれるものじゃないので自動変換は難しそうです..
togakushi
#煽っておきながら返信遅れてスイマセン。。。
> 個人的に
>
> 1. プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよ
> ね
> 2. 運用ドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
> 3. テーマをカスタマイズするコツは? チュートリアルが欲しい。
1. は書いたことはなく、キングファイルに綴じてある鬼のような量を見たことがある程度でしょうか。。。
あまりにも膨大でさっぱり読んでないので内容も覚えてないという。
そもそも誰向けに書かれてるのかさっぱりわかりませんでしたがｗ
2. は多少は協力できそうです。が、現場は長く経験してますが、ずーっと会社が同じだったのでかなり偏ってるとは思います。
3. は自分も教えて欲しいところです。
> - Sphinxドメインっておいしい?
> - reST で blog 書きたい。
> - reST で 論文書きたい。
> - reST で 週報書きたい。
>
> も、もちろん興味あるのですが。
ドメインは美味しそうです。運用ドメイン作りたいですねー。
JavaScriptドメインをいじってみましたが挫け気味ですｗ
# そもそも何が必要なのかも洗い出せてない。
> やりかたですが、テーマ別にGoogle Groupsのディスカッションでスレッド切りつつ、サマリをどこかに
> 載せる(bitbucket?)のは、いかがでしょうか。
>
> # ページとかファイルが廃止になっちゃったので、不便ですねぇ。
google だけであるなら docs を使ってドキュメントの共有でしょうか。
他の勉強会ではサイトも使ったりしてますね。
reST の配布とかは bitbucket がよさそうな気もします。
> 乞うご意見。
＋＋
Komiya Takeshi
> IPAにドキュメントのサンプル集がありますので、このあたり
> から材料としてめぼしいものはピックアップ出来るんじゃない
> かな、と思います。
> http://sec.ipa.go.jp/tool/ep/index.html
>
> 要件定義 のページなどそれっぽいものがそろってそうです。
> http://sec.ipa.go.jp/tool/ep/ep2.html
これはすごいですね。
これを整理して使いそうなものをピックアップするのは一仕事ですね。
案件の規模とかに合わせて松竹梅とパターンができるといいのですけども。
自分は 2-3 ヶ月のプロジェクトが多いので、本当に一握りになりそうですけどね。
Tetsuo Mitsuda
# とりあえずこちらにぶら下げます。
> これを整理して使いそうなものをピックアップするのは一仕事ですね。
確かに多すぎるなーと思って、他に手ごろなものはないかなとオンライン
上にあるか、探してみました。
すると、「即活用！業務システムの開発ドキュメント標準化 」という記事で
よりターゲットを絞ったものがありました。
http://thinkit.co.jp/free/project/4/1/1.html
8回の連載記事になっており、Excelシートがダウンロードできるように
なっています。そのシートなんて「あーあー、こういう感じ。あるある。」
的なものです。
http://thinkit.co.jp/images/project/4/4/dungeon_04_sample.xls
では。
2011年7月26日23:45 Komiya Takeshi <i.tk...@gmail.com>:
--
tcsh
ありがとうございます。
個別のExcelはまだ見れていないのですが、
http://thinkit.co.jp/cert/project/4/1/2.htm
は、自分のイメージする"プロダクトドキュメント"に近いです。
要求分析、基本設計あたりは、そんなに現場による差異が出ないような
気がするのですが、このあたりから自分が使いそうなものを reST化して
みる、というのはいかがでしょう。
まずは連載を読みこんでみますね。
非常に参考になる記事ありがとうございます。
On 7月27日, 午前4:55, Tetsuo Mitsuda <lab1...@gmail.com> wrote:
> 三津田です。
>
> # とりあえずこちらにぶら下げます。
>
> > これを整理して使いそうなものをピックアップするのは一仕事ですね。
>
> 確かに多すぎるなーと思って、他に手ごろなものはないかなとオンライン
> 上にあるか、探してみました。
>
> すると、「即活用！業務システムの開発ドキュメント標準化 」という記事で
> よりターゲットを絞ったものがありました。
>
> http://thinkit.co.jp/free/project/4/1/1.html
>
> 8回の連載記事になっており、Excelシートがダウンロードできるように
> なっています。そのシートなんて「あーあー、こういう感じ。あるある。」
> 的なものです。
>
> http://thinkit.co.jp/images/project/4/4/dungeon_04_sample.xls
>
> では。
>
Komiya Takeshi
今日気になる記事を見かけました。
Design Doc 的な何か用の Wiki 記法によるテンプレ
http://diary.overlasting.net/2010-01-27-4.html
これに(肉付けをしたもの?)が僕のイメージにぴったりです。
話はちょっと変わりますが、いろんなところでドキュメントの話をしていて耳にするのが
「作ったはいいけど更新できていない」なので
僕が欲しいと思っているのは
* 更新できる程度の大きさ (身の丈にあった)
* 不要な情報は含めない (削除する)
* 自動生成できるものは自動生成する
というものです。
例として画面仕様を取り上げると、それがちゃんとメンテされているのか
もしくは、されるべきなのか、ということです。
もちろんお客さんやチーム内での認識合わせのために資料を作ったりもしますが、
それは「維持するもの」「維持しないもの」に振り分けしないといけないでしょう。
単にレイアウトを示した資料は完成後には不要となるでしょう。
そう考えたとき、どのくらい手を抜いてドキュメントを書けるのか、
どのくらいドキュメントに知恵を注げるのか、というのが肝になってくるのでは、と思っています。
また、この前アジャイル開発をやっている人たちとお話ししたのですが、
彼はお客さんの希望がなければドキュメントらしいドキュメントは作らず、
ストーリーカードという要求を書いたカードと
タスク管理ツールだけで済ませることが多いと話していました。
※ 立ち話程度なので、あまり掘り下げて話をしたわけではないですが。
まとまりがないですが、聞きかじったことを情報共有まで。
※ あまりごてごてしたものは Sphinx と合わないようなイメージがあります。
きっとスーツな人たちは更新履歴がどうした、とか前回からの差分を見たい、とか言い出すので。
tcsh
すごく間があいて申し訳ないです。
自分は、Sphinx 自体は大規模か小規模を問わずに使えるツールだとおもっています。
大規模で管理する場合の論点としては、ツール自体よりも
- リポジトリの粒度をどうするか
- includeなどで共通部品として使うパーツの有効範囲をどう制御するか
- 部品化しすぎて密結合なドキュメントになるのをどのように防ぐか
という、ドキュメント管理手法自体の方が問題になりそうにおもっています。
(というか、ずっと迷いながら書いてます。)
一方で、軽く小さくという観点は大事で、小宮さんのいわんとする部分もわかる気がしています。
literalincludeなどのソース引用系のディレクティブつかえば、ソースへのコメントに対して
概要的もしくは付随的なテキストをreSTで記入すれば、工数かからず保守できるドキュメントと
いう夢も遠くないかもしれません。
プロダクトドキュメントの起点として、Design Docs おもしろそうです。
実際、Google でこれをうまく活用しているという事実もあり、これをネタに一回議論して、
最初の rest product document format としてドラフト版つくる & ソースベースの
軽量ドキュメントを考える、のはどうでしょうか。
# 一方で、日本的重量級ドキュメントの要望もあるのは間違いないかと;-)
Komiya Takeshi
> 一方で、軽く小さくという観点は大事で、小宮さんのいわんとする部分もわかる気がしています。
> literalincludeなどのソース引用系のディレクティブつかえば、ソースへのコメントに対して
> 概要的もしくは付随的なテキストをreSTで記入すれば、工数かからず保守できるドキュメントと
> いう夢も遠くないかもしれません。
literalinclude のところがちょっとイメージできていません。
SI 案件では同じ(ような)システムはあまりないので、
共通パーツを使いまわすようなことはあまりイメージできないのです。
> プロダクトドキュメントの起点として、Design Docs おもしろそうです。
> 実際、Google でこれをうまく活用しているという事実もあり、これをネタに一回議論して、
> 最初の rest product document format としてドラフト版つくる & ソースベースの
> 軽量ドキュメントを考える、のはどうでしょうか。
賛成します。
> # 一方で、日本的重量級ドキュメントの要望もあるのは間違いないかと;-)
それはわかるのですが、音頭をとってくれる人がいないと先に進まないと思います。
reSTudy (の周囲)に重量級ドキュメントをよく扱っている方っているんでしょうか?