社内Wikiに情報を書くときに守ってほしい、たったひとつのルール - 無印吉澤

このページについて これは、社内 Wiki に情報を書くときに、私が個人的に守っていて、チームメンバにもできるだけ守ってほしいルールの紹介記事です。このルールを実際に運用するためのコツについても、基本ルールの派生という形で紹介します。 想定する環境 この記事は、社内に Wiki があって、フォーマットが決まったドキュメント（仕様書や手順書など）とは別に、各人がメモを自由に書いて共有できるような環境を想定しています。 Wiki の種類は問いません。PukiWiki、MediaWiki、Confluence、Esa、Redmine などのプロジェクト管理ツール付属の Wiki などなど……何でもいいです。Word 文書などにも適用できなくはないですが、文書を気軽に分けるのが難しい場面には、あまり向かないかと思います。 ルール：「このページについて」という欄をページの先頭に用意し、そのページの概

[pmint]

それってページ名と目次（つまり見出し）にすることでは

[FunnyBunnyDizzy]

読む側が最短で理解できるのが良いドキュメント、ってことでリーダブルコードにちなんでリーダブルドキュメント、みたいな呼び方で啓蒙していきたい。

[futabooo]

わかる

[sgykfjsm]

[wiki][how-to][rule]

[kzm1760]

自分が使ってるWikiでも最初に概要とか書くようにしてるけど、とても共感できる。あと、もう一度「概要」を見直すというのはなるほどという気持ち。

[trollvinter]

wikiはほぼ見るだけの側だけど、思い当たるところがあって参考になる

[ytabuchi]

良さげ

[uunfo]

この記事は社内wikiではないだろうが、概要よりも何よりも先に結論を書け。概要が必要なほど長くなるのはそうならざる場合もあるだろうが構成がおかしいのだと思う。あと無関係な画像も禁止。

[minaryn]

“このページについて”

[odan_703]

社内wikiつくってみたい

[yukung]

これ wiki じゃなくても人が見る可能性のある文書全般これだと思うし、前職だとこれなかったら怒られてた。コードは綺麗だけどドキュメントは雑、みたいなとこだと割となかったりする

[koogawa]

確かに「このページについて」があると助かる。自分は「これは何？」を最初に書くようにしてる

[K2ICE]

"ルール：「このページについて」という欄をページの先頭に用意し、そのページの概要を1〜2文で書く"

[tmsanrinsha]

「このページについて」を書くルール良さそう。tl;drという見出しでもおｋ

[dmutaguchi]

この記事の概要は、記事の先頭に概要を書け、ということだな。

[sds-page]

これも一種の「コメントを書こう」だよね。「コメントと内容が食い違う」はコメントを書かない言い訳にしてはいけない

[fleet1217]

wikiのように文章の加筆修正をする場合には、読み手というよりは書き手の伝えたいことがぶれないようにこのルールを守ることが重要

[itouhiro]

「“このページについて” 欄をページの先頭に用意し、ページ概要を1〜2文で書く」「守ってほしいルールはこれだけ。派生ルール：ページを更新したら見直す。外れる内容は別ページ、本文の品質は高くなくていい」

[shintarowfresh]

ああ、非常にわかる。

[kojiro-s]

ふむ、マネしてみよう

[hogeanonym_20101012]

読む側が期待を裏切られたかどうかはどうでもいいが、書く側が伝えたいことをダイジェストしとくのは大切。

[hiroomi]

"このルールを徹底する目的は、そのページを開いた人に 「このページに、自分がいま知りたい情報が書かれているか」を瞬時に判断する "リードは必要。とは言いつつ目的意識の確認でもあると。

[richard_raw]

参考にします。

[indication]

すばらしい、設計書にも書くべきだ

[akulog]

僕も「背景」を書くことにしてる #toki3_memo

[michiomochi]

なるほど

[eternal-shining]

これは参考になる

[tboffice]

うむ

[codeout]

“社内Wikiに情報を書くときに守ってほしい、たったひとつのルール”

[yojik]

マネして良いかも