PoIC マニュアルの書き方

From PoIC
Jump to: navigation, search

ここでは PoIC マニュアルの書き方について説明します。

はじめに

マニュアルは、第一義的には「自分のためのもの(Built for me)」であるべきです。自分にとって「こういうマニュアルがあったらいいな」というマニュアルを作ります。自分にとって本当役に立つものが、他の人の役にも立ちます。まず自分で読んでみて、何度でも読み返せるものを書きます。料理をする人は、まず自分で食べてみて、本当に美味しいと思えるものを出すはずです。これはマニュアルの場合も同じです。

コアは何?

それを書くことで、読む人・見る人に伝えたい「コア(核)」は何でしょうか。コアはたいてい、一言二言の短いフレーズで表現できます。「(伝えたいことを)一言で言うと?」と自問すると出てきます。コアさえ見付ければ、あとはそれに肉付けしていくだけです。コアが真実であれば、表現方法その他は二次的な問題です。逆に、自分のドックの中で、自然にカードが増えていく話題は何でしょうか。その話題についてカードが増えていくのは、コアがあるからです。カードが何百枚・何千枚に増えたとしても、コアはたった一言の短いフレーズで表現できます。あなたが伝えるべきことは、そのことです。

実験の記録として

PoIC について書く場合、PoIC をひとつの「実験」ととらえると書きやすくなります。

実験の手順書(マニュアル)を書く場合は「再現性」が求められます。同じような状況で、同じような手順を取った時に、同じ結果が得られるということです。もし仮に、自分がいまの記憶をなくしてしまったとき、どういうマニュアルがあれば現状を回復できるでしょうか。なにが必要で、それをどう使うのか、その理由、どんな本を読んで書いたのかが分かると出発しやすいと思います。そのようなことを考えながら書くと、自然と再現性のあるマニュアルができます。

また、「実験」と割り切ることで、「うまくいったこと」だけではなく、「うまくいかなかったこと」も書くことができます。むしろ、うまくいかなかった時に、自分はそれをどう考えたか、どうやって克服したかが、読む人に重要な情報を与えます。実験ですから、成功もあれば失敗もあって当然です。包み隠さず、正直に書くだけです。自分の後ろから付いてくる人がいることを忘れないで下さい。

マニュアルの書き方

作業開始から公開までの流れを説明します。

自分だけの作業空間を作る

私が PoIC マニュアルを書きはじめたころは、それこそページがまっ白の状態からスタートしました。これは、書くことに集中するという意味では、とても作業しやすい環境でした。一方、いまの「メインページ」は情報量が多く、これから文章を書こうとする人にとっては作業がしづらいでしょう。そこで、自分だけの作業空間を作ります。例えば、自分だけのメインページを作ったり、アカウントを作った時に与えられるユーザーページ(User:**)を利用します。そのページをブラウザのブックマークに登録しておき、PoIC マニュアルにアクセスするときは、まずそこに行くようにします。まっさらな空間で、作業に集中します。

逆さまの木

マニュアルを書く時は「逆さまの木」をイメージしながら書くとよいでしょう。ページの上に種・根、中に幹・枝・葉、そして下に果実と並びます。さらにその下には、果実の種からなった、新しい木と新しい果実が並んでいます。PoIC マニュアルの構造は、ちょうどそのような構造をしています。

バージョンを付ける

マニュアルにはバージョンを付けておきます。もう書き終わったと思っても、1ヶ月後・1年後、忘れたころに読み返してみると、まだまだ書くことが出てきます。そもそも、マニュアルは自分の状態に合わせて進化していくものです。バージョンを付けておくことでマニュアルの現在位置が把握できます。また、読む方にとっても、進化の様子が一目で分かります。一つのページの修正・加筆が充分な量に達した時は、メインページ(Updated 2009.**.**)と目印を付けておきましょう。

マニュアルは、読んでは書き、書いては読むのくり返しで磨きをかけていきます。自分の書いた文章を読み返していると、「これも書き足しておこう」とアイディアが浮かんできます。アイディアが浮かんだその時に書き加えるようにします。読んでいて気になるところ、引っかかるところは、気の済むまで修正・加筆を繰り返します。どんなにこまかい書き直しでも構いません。ページの名前は move タブから変更できます。こちらも気の済むまで変更して下さい。PoIC マニュアルがどう進化してきたかは、各ページの history (ページ上部にある history タブ)で確認できます。最初期からたどっていくと、どうやってこのマニュアルが形作られてきたかが分かるので、参考にして下さい。

画像を貼る方法

ページに貼る画像は、ページ左にあるサイドバーの toolbox の中の「Upload file」からアップロードします。foo.jpg という画像(横幅180 px)をページの右側に貼るには、ウィキのテキストに以下の文字列を挿入します。

[[Image:foo.jpg|right|thumb|180px|画像の簡単な説明(拡大する)。]]

画像のサイズは、横長の場合は 240 px X 180 px、縦長の場合は 180 px X 240 px を基本とします。Flickr にアカウントを持っている方は、All Sizes から Small をダウンロードして使用するとよいです。オリジナルの画像へのリンクもあった方がよいです。説明文の最後に「(拡大する)」を加え、flickr の画像へのリンクを張っておきます。PoIC マニュアルにアップロード可能なファイル形式は、gif・png・jpg・xls・doc・ppt・pdf・txt の8種類です。

参考資料を付ける

PoIC にマニュアルを投稿する時は、かならず最後に参考にした本のリスト(参考資料)を付けて下さい。参照カードの場合と同じで、参考資料のないマニュアルはまったく役に立ちません。ちなみに、最初期の PoIC マニュアルの参考資料は、カード五書、「超」整理法、Knowledge Discovery in Databases の7つでした。PoIC システムの起源はこの7つだけです。

公開する

ある程度文量が増え、かたちが出来てきたところで、公開しましょう。メインページの「最近のニュース」の上に、以下のような形式で、タイトルとリンクを作って下さい。

== ○○○○ ==
* ○○○○ <font color="red">(Updated 2009.**.**)</font>
** ○○○○
** ○○○○

タイトルはいつでも変更できます。初めは暫定的なもので構いません。

自分のページを見てくれる人がいるということは、文章を書く上で、たいへん励みになります。よって、文章がすべてが完成してからではなく、制作の途中で公開することをお勧めします。文章は、まめにアップデートし、バージョンが整数のところでの完成を目指します(e.g. v. 1.0、v. 2.0)。ちなみに、「PoIC を通じて見えたこと」は、この状態から公開をはじめました。

自分のブログや Flickr にオリジナルの記事がある場合は、ウィキのページからオリジナルの記事へのリンクを張って下さい。逆に、自分のブログや Flickr にもリンクを張り、自分のページへのアクセス数を増やして下さい。こうして情報の通りが良くなります。

ウィキに関する質問

ウィキに関して分からないことがあるときは、まず Google で検索してみて下さい(例えば、MediaWiki 画像、など)。たいていの答えは見つかります。検索先が英語だったり、私(Hawk)に聞いた方が早い場合もありますので、気兼ねなく聞いて下さい。私への連絡方法は以下の4つです。

  1. ブログにコメントを残す
  2. ウィキからメールを送る
  3. Flickr Mail を使う
  4. E-メールを送る

メールの内容は基本的に非公開ですが、よくある質問や再現性のある場合は、このページに反映させる場合があります。

コントロール

マニュアル作成者や管理者がチェックすべきページはいくつかあります。「中の人」は、PoIC ウィキを裏側から見るようにして下さい。

この他にも、toolbox 内の「Special pages」からさまざまな管理用ページにアクセスできます。

参考になるページ

MediaWiki ヘルプ(日本語版)