2004年中途入社の koic です。来月で入社17年。長いですね。 17年の間で人や技術が流転する長い勤務の中で伝承の途切れを観測していることから、私がいまの勤務先に入ったころ Wiki への考え方への影響を受けたものを発掘してみました。今回、私的解釈を交えて一般公開します。
はじめに
本記事で取りあげるのは 2006年以前に「ドキュメント記述の心構え」 (WikiName は DeciplinesOfWritingDocumentsOnWiki) として作成された Wiki ページを掘り起こしたものです。かつて角谷さんが牽引していたプロジェクトにて引き継がれていた文書で原文ママで置いています。Wiki 記法は数多ある Wiki クローンの Ruby 製の Hiki による記法です。
『ドキュメント記述の心構え』原文
{{toc}}
! 木構造よりも、ネットワーク構造を好め
* Wikiページはツリーノードというよりは、ネットワークノードだと思え。
* 孤立したノード間を繋げるものがハイパーリンクである。
* ただし、視点ごとに整理した木構造のインデックスページの作成は、奨励される。
! ネストしたリストよりも、見出しによる構造化を好め
*リストは使い易いが、それゆえに濫用しがち。それは本当にリストか？
* リストはインデントが深い
* 見出しを使えばTOCプラグインでページの目次を自動生成できる
! リストで文章を区切るよりも、空行をあけてPタグでレンダリングせよ
* それは本当にリストか？ 簡潔な地の文の連続を、適切なまとまりで段落とせよ
! 安易に項目追加する前に、リオーガナイズを検討せよ
* 特定カテゴリの一覧となるインデックスページを適切なサイズで分割せよ
! 正規化と重複の均衡点を探せ
* DRYと読み下しやすさとのバランスに唯一無二の解決策はない。コンテキスト毎での最適なバランスを探せ
! PREとQUOTEを使い分けよ
* 難しいよね
! リオーガナイズのメカニクスを用意せよ
* TODO: まとめてみること :-)
私的解釈
掘り起こした文書への私的解釈です。
{{toc}}
見出しによる目次 (Table of Contents) の生成を作ることをページ自体にも適用して、ドキュメント自体がサンプルになっている好例。
木構造よりも、ネットワーク構造を好め
のちの江渡さんの『パターン、Wiki、XP ~時を超えた創造の原則』に通じるので、そちらを読むと理解が深まると思います。
ネストしたリストよりも、見出しによる構造化を好め
これは本当にそう。自分も個人ブログの方にエントリにしている。ここではさらに見出しにすべき理由として TOC の生成を挙げている点が秀逸。
リストで文章を区切るよりも、空行をあけてPタグでレンダリングせよ
その辺の書籍などを読んでも箇条書き中心で構成されているものはレアだと思う。散文的な箇条書きに頼るだけではない文章を書く力は大事。
安易に項目追加する前に、リオーガナイズを検討せよ
これはちょっと難しかった。問題の背景をうまく掴めていないので (あるいは忘れてしまったようで) 、よく理解できていない。
正規化と重複の均衡点を探せ
同一の文章がページにまたがる物差しについて挙げられていると思う。コンテキストによって補完される内容であれば重複して問題ないと思う。一方でコンテキスト非依存であれば独立したページとして参照されるものだと思っている。DCI (Data Context Interaction) はヒントになりそう。
PREとQUOTEを使い分けよ
コードは PRE を使い、引用は QUOTE を使うで良いと思うが、当時の疑問を分かっていない (私は角谷さん卒業後の後期に参加していた) 。
リオーガナイズのメカニクスを用意せよ
ここで未完となっていて、続きは各人で Wiki を育てていこうといった感じになっていると受け取っている。この記事を種子にして育つと嬉しい。
、、、とここまで書いたあとフェローの角谷さんからコメントをいただく機会がありました。いわくこの項目は「qwik から繋がり 2020年のいま Scrapbox で実現されている」とのことでした。Scrapbox を使った事例の URL をあげておきます。
続きは各自の研究に譲ります。
おわりに
現代ではネットワークを辿る方法に限らず全文検索するという手法がより一般的になっていますが、ハイパーテキストとハイパーリンクからなる Web ページの文書構造や相関関係というインターネットの基礎概念のひとつについて考える良いきっかけになればと思い発掘してみました。その考え方は Wiki ページに限らず Markdown や AsciiDoc による文書作成にも転用できるでしょう。
以上、3年越し17年ものの復刻作業結果の共有です。個人的にはのちのドキュメントの書き方にも影響を受けており、かつてプレゼンテーションとして起こしたりしました。文書構造に対して新たに考えるきっかけになれば幸いです。
We are going to the Timeless Way of...
創業40年の永和システムマネジメントでは一緒にソフトウェア開発のアカシックレコードを刻んで行こうというメンバーを募集しています。
