Welcome to reSTudy

31 views
Skip to first unread message

tcsh

unread,
Jun 25, 2011, 9:04:54 PM6/25/11
to reSTudy
波田野 です。

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

unread,
Jun 25, 2011, 9:54:42 PM6/25/11
to res...@googlegroups.com
清水川です。
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

unread,
Jun 26, 2011, 12:54:43 AM6/26/11
to reSTudy
波田野 です。

# 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

unread,
Jun 27, 2011, 6:57:34 PM6/27/11
to res...@googlegroups.com
togakushiです。
reSTudyに参加してみました。よろしくお願いします。

> 3. コンテンツは reST で記述し、Mercurial をつかった分散バージョン管理下に置きたい。
> (マスターは、BitBucket に置く、みたいな感じ。)
> コンテンツから clone したものは自由改変OK。逆に自由改変がNGなものはコンテンツには
> 置かない。

この部分は Mercurial の使い方がよくわかってない人が困るのでは、、、と思いました。
# 参加者を見る感じだとみんな使えそうですが。

Mercurial の使い方を reST でドキュメント化してあると嬉しいかなと。
公式マニュアルだけでも足りそうですが、グループに特化した使い方や
ルールなどがまとまってると、実際に使ってる例として普及に役立つと思います。

---
togakushi

shimizukawa takayuki

unread,
Jun 27, 2011, 7:08:55 PM6/27/11
to res...@googlegroups.com, res...@googlegroups.com
清水川です。

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

unread,
Jul 24, 2011, 3:32:20 AM7/24/11
to reSTudy
波田野 です。

あっという間に一ヶ月たっちゃいました。すいませんm(..)m

個人的に

1. プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよ

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

あたりから手をつけはじめたい気分です。

- Sphinxドメインっておいしい?
- reST で blog 書きたい。
- reST で 論文書きたい。
- reST で 週報書きたい。

も、もちろん興味あるのですが。



やりかたですが、テーマ別にGoogle Groupsのディスカッションでスレッド切りつつ、サマリをどこかに
載せる(bitbucket?)のは、いかがでしょうか。

# ページとかファイルが廃止になっちゃったので、不便ですねぇ。


昔のMLさながらですが、下記スレッドの起点メールを投げるかんじでやってみたいと思います。

1. プロダクトドキュメント
2. 運用ドキュメント
3. テーマのカスタマイズ
4. Sphinxドメイン
5. reST で blog
6. reST で 論文
7. off topic


乞うご意見。

Komiya Takeshi

unread,
Jul 24, 2011, 12:20:24 PM7/24/11
to res...@googlegroups.com
@tk0miya です。

> 1. プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよ
> ね
> 2. 運用ドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
> 3. テーマをカスタマイズするコツは? チュートリアルが欲しい。
>
> あたりから手をつけはじめたい気分です。

3 はともかく、1, 2 って誰かディスカッションできそうですかねー?
僕はプロダクトはやってなかった(正確に言うとやってたけどドキュメントがなかった)し、
運用もたいして触れていないのでどっちもちゃちゃを入れる程度になりそうです。

3 はやったことがないものの、手を出せばできるぐらいの距離感だと思ってます。
1 は代わりに SI 案件のドキュメントという方向もあるのでは。
それであれば僕も協力できます。(それでもうちの会社はあんまり書いてないですが…)


積極的反対ではまったくないのですが、自分の立ち位置を宣言してみます。


> - Sphinxドメインっておいしい?

いまのところクラスリファレンスが書ける程度の機能しかないですよね。
開発系の資料であればともかく、その他のもので使えるかはあやしそうなきがします。

Takayuki Shimizukawa

unread,
Jul 24, 2011, 7:09:41 PM7/24/11
to res...@googlegroups.com
清水川です。

小宮さんのコメントにほぼ同じなので、差分だけ書きます。

2011年7月25日1:20 Komiya Takeshi <i.tk...@gmail.com>:


>> - Sphinxドメインっておいしい?
>
> いまのところクラスリファレンスが書ける程度の機能しかないですよね。
> 開発系の資料であればともかく、その他のもので使えるかはあやしそうなきがします。

Sphinxドメインは拡張が可能なrole集合と言えるので、例えば「運用」ドメイン
として出力をカスタマイズしたい複数のroleを定義する、なんてことが、拡張
としては比較的簡単に作ることができます。

既存のものについては小宮さんのコメント通り、関数やクラスのハイライトと
クロスリファレンスをしてくれるドメインしか用意されていないので、「おいしい」
ところがあるとすれば上記のように独自ドメインを作ったときじゃないかと
思います。

--
清水川.jp

tcsh

unread,
Jul 24, 2011, 8:04:11 PM7/24/11
to reSTudy
小宮さん、清水川さん
ありがとうございます。

まずは、簡単なものでもいいので、テンプレート集を作りたい
と思っています。

# 以前のメールにあった、OSCでの声に応える、みたいな
# イメージです。

SIer経験が殆どないのでイメージし切れていないのですが
まずは、こんなシート、こんなテンプレあるよね的なブレスト
からできればと思っています。

プロダクトドキュメントについては、要求仕様書、機能要件、
非機能要件、概要設計書、機能一覧、画面設計書、詳細設計書
みたいなものが、あるのかな、と。
(個人的には今、この辺りの知識不足で苦労してたりします。)


運用ドキュメントについては、個人的に作業カタログ(一覧)と
いうものを考えていて、Excel版から移植したいと思っています。


取り急ぎ、こんなイメージです、というあたりを。

皆さんの活動への期待、意欲も伺いたいです。



On 7月25日, 午前8:09, Takayuki Shimizukawa <shimizuk...@gmail.com> wrote:
> 清水川です。
>
> 小宮さんのコメントにほぼ同じなので、差分だけ書きます。
>
> 2011年7月25日1:20 Komiya Takeshi <i.tkom...@gmail.com>:

Komiya Takeshi

unread,
Jul 24, 2011, 10:42:12 PM7/24/11
to res...@googlegroups.com
@tk0miya です。

> SIer経験が殆どないのでイメージし切れていないのですが
> まずは、こんなシート、こんなテンプレあるよね的なブレスト
> からできればと思っています。
>
> プロダクトドキュメントについては、要求仕様書、機能要件、
> 非機能要件、概要設計書、機能一覧、画面設計書、詳細設計書
> みたいなものが、あるのかな、と。
> (個人的には今、この辺りの知識不足で苦労してたりします。)

それでいうとプロダクトであげてもらったものとプロダクトは似たようなものですね。
ぱっと思いつくのはデータベース定義、利用マニュアルとかぐらいでしょうか。

その上でどれを作るのか、メンテナンスするのか、ですよね。
うちは小さいプロジェクトだったり、お客さんがドキュメントを要求しないなどのコスト的な理由で、
最低限の小さいドキュメントしかない (もしくは存在しない)状態ですね。

そもそもよく言う「概要設計書」と「詳細設計書」の違いもあんまり分かってないです。
これはどこから手を付けていいのか分からない感じですね。

おそらく清水川さんのドキュメントのポートフォリオ? がベースになるんでしょうね。
http://sphinx-users.jp/articles/business-document-sample/2portfolio/index.html

Komiya Takeshi

unread,
Jul 24, 2011, 10:48:50 PM7/24/11
to res...@googlegroups.com
@tk0miya です。

>>> - Sphinxドメインっておいしい?
>>
>> いまのところクラスリファレンスが書ける程度の機能しかないですよね。
>> 開発系の資料であればともかく、その他のもので使えるかはあやしそうなきがします。
>
> Sphinxドメインは拡張が可能なrole集合と言えるので、例えば「運用」ドメイン
> として出力をカスタマイズしたい複数のroleを定義する、なんてことが、拡張
> としては比較的簡単に作ることができます。

どういうものを「ドメイン」として定義するのか検討するとよいということですかね。

マークアップの数を増やすと、書き分けされなくなって、
逆に使われなくなるのではないかと懸念してます。
ほとんど :term: でいいんじゃないかという気がするのですが、
積極的にロールを与えたいケースってどんなものですかね。

※ セマンティック度をあげるとたいていの人は音を上げると僕は予想しているので、
  よっぽど汎用的なものでなければ用意しない方が使われると思っています。

hokorobi

unread,
Jul 24, 2011, 11:35:01 PM7/24/11
to reSTudy
hokorobi です。
よろしくお願いします。

> 皆さんの活動への期待、意欲も伺いたいです。
こんなドキュメントを reST で書いたら、こんな感じで良かったよ、
こんな感じでまずかったよという話が聞けると良いなと思っています。


私の場合、ユーザが使うシステムの使用手順書を reST で書いて、
Sphinx で HTML にして説明したときは、なかなか感触が良かったな
という経験があります。

説明をするときは大抵 PowerPoint を使っているのですが、
見目よく手順書ができていて、それをうまいこと説明できればいらないな~とかとか。
(特殊な話のような気もしますが……)

---
hokorobi @h0k0r0bi

Tetsuo Mitsuda

unread,
Jul 25, 2011, 8:31:08 AM7/25/11
to res...@googlegroups.com
三津田です。
あっ、はじめまして。よろしくおねがいしますです。

> 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

unread,
Jul 25, 2011, 5:48:48 PM7/25/11
to reSTudy
波田野 です。

ありがとうございます!

結構ボリュームある一方で、それほど整理されていない印象がありますが、
この中で自分達が使いそうなものをピックアップして、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
>
> では。
>
> 2011年7月25日9:04 tcsh <tcsh.csh...@gmail.com>:

tcsh

unread,
Jul 25, 2011, 5:52:22 PM7/25/11
to reSTudy
波田野 です。

On 7月25日, 午後12:35, hokorobi <hokorobi.hokor...@gmail.com> wrote:
> こんなドキュメントを reST で書いたら、こんな感じで良かったよ、
> こんな感じでまずかったよという話が聞けると良いなと思っています。
>
> 私の場合、ユーザが使うシステムの使用手順書を reST で書いて、
> Sphinx で HTML にして説明したときは、なかなか感触が良かったな
> という経験があります。

おー、すばらしいです。
感触が良かった点をもちょっと具体的にお聞きしたいです。


> 説明をするときは大抵 PowerPoint を使っているのですが、
> 見目よく手順書ができていて、それをうまいこと説明できればいらないな~とかとか。
> (特殊な話のような気もしますが……)

うちも、ppt文化なので、それを少しでも減らせれば嬉しいなぁとおもっています:-)

# pptは構造的に書かれるものじゃないので自動変換は難しそうです..

togakushi

unread,
Jul 25, 2011, 7:13:20 PM7/25/11
to res...@googlegroups.com
とがくしです。

#煽っておきながら返信遅れてスイマセン。。。

> 個人的に
>
> 1. プロダクトドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよ
> ね
> 2. 運用ドキュメントってこういうのが必要で、reSTで書くときはこんな感じのテンプレートが必要で、成果物イメージってこんな感じだよね
> 3. テーマをカスタマイズするコツは? チュートリアルが欲しい。

1. は書いたことはなく、キングファイルに綴じてある鬼のような量を見たことがある程度でしょうか。。。
あまりにも膨大でさっぱり読んでないので内容も覚えてないという。
そもそも誰向けに書かれてるのかさっぱりわかりませんでしたがw

2. は多少は協力できそうです。が、現場は長く経験してますが、ずーっと会社が同じだったのでかなり偏ってるとは思います。

3. は自分も教えて欲しいところです。

> - Sphinxドメインっておいしい?
> - reST で blog 書きたい。
> - reST で 論文書きたい。
> - reST で 週報書きたい。
>
> も、もちろん興味あるのですが。

ドメインは美味しそうです。運用ドメイン作りたいですねー。
JavaScriptドメインをいじってみましたが挫け気味ですw
# そもそも何が必要なのかも洗い出せてない。

> やりかたですが、テーマ別にGoogle Groupsのディスカッションでスレッド切りつつ、サマリをどこかに
> 載せる(bitbucket?)のは、いかがでしょうか。
>
> # ページとかファイルが廃止になっちゃったので、不便ですねぇ。

google だけであるなら docs を使ってドキュメントの共有でしょうか。
他の勉強会ではサイトも使ったりしてますね。
reST の配布とかは bitbucket がよさそうな気もします。

> 乞うご意見。

++

Komiya Takeshi

unread,
Jul 26, 2011, 10:45:28 AM7/26/11
to res...@googlegroups.com
@tk0miya です。

> IPAにドキュメントのサンプル集がありますので、このあたり
> から材料としてめぼしいものはピックアップ出来るんじゃない
> かな、と思います。
> http://sec.ipa.go.jp/tool/ep/index.html
>
> 要件定義 のページなどそれっぽいものがそろってそうです。
> http://sec.ipa.go.jp/tool/ep/ep2.html

これはすごいですね。
これを整理して使いそうなものをピックアップするのは一仕事ですね。
案件の規模とかに合わせて松竹梅とパターンができるといいのですけども。

自分は 2-3 ヶ月のプロジェクトが多いので、本当に一握りになりそうですけどね。

Tetsuo Mitsuda

unread,
Jul 26, 2011, 3:55:21 PM7/26/11
to res...@googlegroups.com
三津田です。

# とりあえずこちらにぶら下げます。

> これを整理して使いそうなものをピックアップするのは一仕事ですね。

確かに多すぎるなーと思って、他に手ごろなものはないかなとオンライン
上にあるか、探してみました。

すると、「即活用!業務システムの開発ドキュメント標準化 」という記事で
よりターゲットを絞ったものがありました。

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

unread,
Jul 26, 2011, 7:05:07 PM7/26/11
to reSTudy
三津田さん
ありがとうございます。

個別の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
>
> では。
>
> 2011年7月26日23:45 Komiya Takeshi <i.tkom...@gmail.com>:

Komiya Takeshi

unread,
Jul 27, 2011, 1:32:34 AM7/27/11
to res...@googlegroups.com
@tk0miya です。

今日気になる記事を見かけました。

Design Doc 的な何か用の Wiki 記法によるテンプレ
http://diary.overlasting.net/2010-01-27-4.html


これに(肉付けをしたもの?)が僕のイメージにぴったりです。


話はちょっと変わりますが、いろんなところでドキュメントの話をしていて耳にするのが
「作ったはいいけど更新できていない」なので
僕が欲しいと思っているのは
* 更新できる程度の大きさ (身の丈にあった)
* 不要な情報は含めない (削除する)
* 自動生成できるものは自動生成する
というものです。


例として画面仕様を取り上げると、それがちゃんとメンテされているのか
もしくは、されるべきなのか、ということです。

もちろんお客さんやチーム内での認識合わせのために資料を作ったりもしますが、
それは「維持するもの」「維持しないもの」に振り分けしないといけないでしょう。
単にレイアウトを示した資料は完成後には不要となるでしょう。

そう考えたとき、どのくらい手を抜いてドキュメントを書けるのか、
どのくらいドキュメントに知恵を注げるのか、というのが肝になってくるのでは、と思っています。


また、この前アジャイル開発をやっている人たちとお話ししたのですが、
彼はお客さんの希望がなければドキュメントらしいドキュメントは作らず、
ストーリーカードという要求を書いたカードと
タスク管理ツールだけで済ませることが多いと話していました。
※ 立ち話程度なので、あまり掘り下げて話をしたわけではないですが。


まとまりがないですが、聞きかじったことを情報共有まで。

※ あまりごてごてしたものは Sphinx と合わないようなイメージがあります。
  きっとスーツな人たちは更新履歴がどうした、とか前回からの差分を見たい、とか言い出すので。

tcsh

unread,
Aug 18, 2011, 7:00:20 PM8/18/11
to reSTudy
波田野 です。

すごく間があいて申し訳ないです。

自分は、Sphinx 自体は大規模か小規模を問わずに使えるツールだとおもっています。

大規模で管理する場合の論点としては、ツール自体よりも
- リポジトリの粒度をどうするか
- includeなどで共通部品として使うパーツの有効範囲をどう制御するか
- 部品化しすぎて密結合なドキュメントになるのをどのように防ぐか
という、ドキュメント管理手法自体の方が問題になりそうにおもっています。
(というか、ずっと迷いながら書いてます。)


一方で、軽く小さくという観点は大事で、小宮さんのいわんとする部分もわかる気がしています。
literalincludeなどのソース引用系のディレクティブつかえば、ソースへのコメントに対して
概要的もしくは付随的なテキストをreSTで記入すれば、工数かからず保守できるドキュメントと
いう夢も遠くないかもしれません。

プロダクトドキュメントの起点として、Design Docs おもしろそうです。
実際、Google でこれをうまく活用しているという事実もあり、これをネタに一回議論して、
最初の rest product document format としてドラフト版つくる & ソースベースの
軽量ドキュメントを考える、のはどうでしょうか。


# 一方で、日本的重量級ドキュメントの要望もあるのは間違いないかと;-)

Komiya Takeshi

unread,
Aug 20, 2011, 4:06:21 AM8/20/11
to res...@googlegroups.com
@tk0miya です。

> 一方で、軽く小さくという観点は大事で、小宮さんのいわんとする部分もわかる気がしています。
> literalincludeなどのソース引用系のディレクティブつかえば、ソースへのコメントに対して
> 概要的もしくは付随的なテキストをreSTで記入すれば、工数かからず保守できるドキュメントと
> いう夢も遠くないかもしれません。

literalinclude のところがちょっとイメージできていません。
SI 案件では同じ(ような)システムはあまりないので、
共通パーツを使いまわすようなことはあまりイメージできないのです。

> プロダクトドキュメントの起点として、Design Docs おもしろそうです。
> 実際、Google でこれをうまく活用しているという事実もあり、これをネタに一回議論して、
> 最初の rest product document format としてドラフト版つくる & ソースベースの
> 軽量ドキュメントを考える、のはどうでしょうか。

賛成します。

> # 一方で、日本的重量級ドキュメントの要望もあるのは間違いないかと;-)

それはわかるのですが、音頭をとってくれる人がいないと先に進まないと思います。
reSTudy (の周囲)に重量級ドキュメントをよく扱っている方っているんでしょうか?

Reply all
Reply to author
Forward
0 new messages