wikiと文書構造について

会社の先輩が話してくださったことをまとめたのでアップします。
この話を聞いてから、文書構造というものを意識しています。
練習あるのみ!

                                                                                        • -

【wikiとは】
ハイパーテキスト(HTML等)はwebのためのモノで、人間には書きづらいし読みづらいという課題がある。
wikiは、独自の記法でHTMLを人間向け(プレーンテキスト)にしたもので、
そのプレーンテキストを自動的にハイパーテキストに変換してくれる。

【wikiを書く理由】

  • 情報を他人に伝えるため
  • 未来の自分に伝えるため

あとで読んで理解できないと意味がないので、伝えるということを意識して書く。
(これは達人プログラマーにも出てくる)

【wikiとブログの違い】

  • ブログは日付単位の更新
  • wikiは項目単位の更新

「ブログ wiki 違い」でググると色々でてくるから、その内容についてみんなで話してみると面白いかも。

【wiki記法と文書構造】
wikiを書くことは、文書構造を考える練習にもなる。
続けていれば普段から文書構造を意識したメールが書けるようになる。

ポイントは、まずタイトルを意識すること。
何のことについて書いているのか、分かりやすく明確にすることが大切。
見出しや箇条書きは、本が参考になる。
箇条書きを多く使ってしまいがちだが、実は箇条書きは読む側にとってはつらい。
(意味がつかみ取りにくいことが多い)
箇条書きにする前に、それは本当に箇条書きにすべきなのかを考える。

見た目と文書構造は別物。
例えば、qwikの<見出し2>と<見出し3>はブラウザで見ると区別しにくいが
それはスタイルシートの問題であり、wiki記法では文書構造を表現する。

分かりやすい技術文章の書き方(http://oalp.org/doc/writing/)が参考になる。

【wikiname】
タイトルと同様に、そのページは何についてのページなのかを見てすぐ分かるような名前にする。
(名前付けが重要なのはプログラムと一緒!)
wikinameはwikiでフラットに一意なもの。
CamelCaseの習慣をつけ、単語の最初の文字を大文字にする。
英単語でつけることを心がける。

【質問&回答】
Q : 箇条書きに説明をつけようとすると、変な構造になると思うのですが、どうしたらいいですか?
A:箇条書きは箇条書きだから説明したくなったら、それは見出し。ヘッダ1は何個あってもいいし、ヘッダ2はもっともっと使うべき。

Q : 文章はどれくらいの長さで改行するのがいいですか?
A:改行はその文章全体で統一されていればOK。プロジェクトであれば、プロジェクトの書き方に合わせる。

Q:内容が少なくても、違う話なら見出しをつけた方がいいですか?
A:全体のバランスは考えた方がいいけど、見出しは中身のボリュームによってつけるものではない。

Q:どういう時に箇条書きを使えばいいのか、分からなくなってきたのですが…
A:箇条書きには、箇条に書きたいことを書く。つまり文章ではない。本などを参考にしてみてください。

Q:これらを意識して書くと、ものすごく時間がかかりそうなのですが…
A:最初から早く上手に書けるはずはないから、上手く書こうとすれば絶対に時間はかかる。練習を重ねてください。