開発者向けのWikiを設定するためのベストプラクティス構造をお探しですか？

ドキュメンテーション、コミュニケーション、知識共有の実績がまだないチームを管理します。チームがこの領域を簡単に始められるように、フレームワークを設定したいのですが。

完璧な構造を前もって作ることに集中しすぎないでください。有機的に成長させましょう。重要なのはコミュニケーションの文化とプロセスです。

以下は、チームWikiを維持するためのヒントです。

基礎

価値フィードバック

メール、Wikiページのコメント（最も便利なもの）、メッセンジャー、会話など、フィードバックを求め、収集して記録します。

• フィードバックの記録

  • Q：現在、情報を適切に処理する時間がない場合はどうなりますか？
  • A：そのままページに保存します-将来の処理のために、次のように通常の読者から非表示にします。{excerpt:hidden=true}information to be processed later{excerpt}

• フィードバックの処理

  • できるだけ速くそれを行うようにしてください。あなたや送信者にすぐにわかる詳細とコンテキストは、1日、1週間、1か月後に忘れられる可能性があります  
  • フィードバックで指摘された問題の代替ソリューションを検討してください。例：
    • （フィードバック）ちょっと必要な情報が役に立たないものと混ざっている
    • （間違ったアクション）OK不要なものを削除します
    • （正しいアクション）OK情報をあなたの興味の1つと他の誰かの興味があるかもしれない残りに分割します

長期的な作業を示唆する提案の処理

• Q：「他の数千ページに文書化されているすべての関連データを収集して並べ替える」という提案があった場合はどうなりますか？
• A： TODO-sセクションをページに追加し（まだない場合）、このセクションに提案を記録します。後で、それを使用して進捗状況を追跡することもできます
  update DD.MM.YYYY: 475 pages of 1000 are processed

間違っていると思われる提案の処理

補足として、提案の提出者に説明を求めても問題はありません。ただし、最初に仕事の一部を行うほうがよいでしょう。

• レビュー日を考慮して、ページ履歴を確認してください。提出者がすでに修正されている古いバージョンの問題を指摘する可能性は常にあります
• 参照されているページ/セクションをよく見て、自分自身に尋ねてください。彼/彼女がそのように考えさせる原因は何でしょうか？
• （上記のようなトリックで少しトレーニングした後）すべてではないにしてもほとんどの場合、そこには改善の明確な領域があることがわかります。
  • たとえば、ページのどこかに実際に存在する情報の不足についてユーザーが不満を言っていると想像してください。一見間違っているように見えても、そのような苦情はページに深刻な問題があることを示しています。それに値する可視性を与えると、ページが改善されます。

完璧よりも速く

レビューとフィードバックに依存します。何かが本当に修正が必要な場合は、時間があなたのためにそれを整理します

• これは自己レビューにも当てはまります。ページに入れたいもののドラフトを記録し、1時間後（または1日後、1週間後）に自分でレビューします。このトリックは不思議に思われます。
• 最初の試みで物事を完璧にするために時間を無駄にしないでください-それは不可能です
  • やっと受け入れられるようになったらすぐに情報を記録し、興味のある人にそれをレビューするように頼む

大胆になります

ページを更新するときは大胆に：問題の修正、文法の修正、事実の追加、表現の正確性の確認など。

• 上記はウィキペディアの原則に基づいており、ウィキペディアでよく説明されています
  • ...しかし、注意してください-共通の善を大事にし、無謀に編集しないでください：上記の原則の明確化、これ
    もWikipediaで説明されています

高度な

感謝する

フィードバックを与える人々は貴重な資産です、彼らに感謝してください。これらの人々はあなたのページを読むだけでなく、彼らのフィードバックを提供するためにも時間と労力を費やしました。ユーザーの大多数はあなたにそれほど寛大ではありません。彼らの考えを共有する人々はあなたの聴衆の「クリーム」です、彼らの貢献に感謝してください。

TLA-sを説明する

TLAがわからない場合は、-あなたはポイントを持っています

• 可能であればリンクを使用してください：TLA

質問への回答を記録する

他人の時間を尊重する- 回答を記録する

• 質問に答えるのに1秒かかるかもしれませんが、代わりに質問した人について考えますか？（S）彼はあなたのページを読んで、答えを見つけようとし、あなたに連絡してあなたの答えを待つのに時間をかけました。ページで答えを記録しておけば、次の男がこの質問をするまで、その時間を節約できます。
• 自分の質問に対する回答を記録します。あなたに不明確なことは、次の読者には不明確かもしれません。

疑問符を使用する

疑問がある場合は、疑問符を使用してください

• 例としてのConfluence構文：(?) 例：<this info> needs checking
• このようにして、どの読者も必要な情報の種類を明確に見ることができます。誰かがあなたが物事を明確にするのを助けることができる可能性が高いです

リンクはあなたの友達です

• DRY-代わりにリンクを提供できる場合は情報をコピーしようとしないでください
• 必要なときに要約することを学ぶ
  • 一部のリンク -これは何ですか？
  • リンク -ウィキペディア、誰でも編集できる無料の百科事典

ビジュアルが重要

• 時間があるときは、読者が自分の意思でポイントを獲得するのが簡単かどうか自分に尋ねて、ページを自己確認します。
• 構造化されていない意識の流れから物質を見つけるのは非常に難しい場合があります

  ^{...私は彼にイエスと言うように言われるまで彼を導くことができるすべての喜びを彼に与えました、そして私は最初に答えませんでした私は彼がマルベイとスタンホープとヘスターについて知らなかった非常に多くのことを考えていた海と空を見渡しました父と年老いたキャプテングローブとすべての鳥を弾く船員が飛んで、私は彼らが首をかしげて、ガバナーズハウスの前の桟橋とセントリーで呼び出した皿を洗っていると言います。彼らのショールと彼らの背の高いコームとオークションでの朝の笑いギリシャ人とユダヤ人とアラブ人と悪魔は、ラービーシャロンズと貧しいロバの外を駆け巡るヨーロッパとデュークストリートと家禽市場の端から誰が他に誰を知っているか半眠りに入ると、マントの漠然とした仲間たちは階段の陰で眠り、数千年前の雄牛のカートと古いお城の大きな車輪はい、そして王様のような白とターバンのハンサムなムーア人たちが、小さなお店に座って、ポンダスの古い窓のあるロンダに座るように頼んでいます2つの目を見つめる格子は恋人が鉄にキスするために格子を隠し、ワインショップは夜半オープンで、カスタネットと夜はアルゲシラスでボートに乗り遅れました。夜は、ランプとOでひどいディープダウントレントOと海で穏やかな夜を過ごしました。海の深紅色は時々火とアラメダ庭園の見事な夕日とイチジクの木が好きで、すべての奇妙な小さな通りと​​ピンクと青と黄色の家、ローズガーデンとジェサミンとゼラニウムとサボテンと私がいた少女としてのジブラルタル山の花はい、髪の毛にバラをアンダルシアの女の子が使用したり、私は赤いはいを着たり、ムーア人の壁の下で彼に私にキスをしたり、私も彼と同じように考えたりして、私は彼に別の人と同じように目を向けてもらい、もう一度彼に尋ねるように頼みましたはい、私の山の花です。最初に彼の腕を彼の周りに置き、私を彼に引き寄せました。そうすれば彼は私の胸をすべて香るように感じ、彼の心は狂ったようになり、そして私はそう言ったのです。}

リラックスして楽しんでください

通常、ページの読者は真面目である必要はありません。

• 楽しむことが適切だと感じたとき

リンク腐敗と戦う

• ページやリソースを移動してもよろしいですか？
  いいですね、ブックマーク、メールアーカイブ、ドキュメントなどのどこかにリンクを張っている人たちについて考えてください。
• ページまたはドキュメントを（再）移動するときは、以前に配置されていた場所にプレースホルダーを保持し、訪問者が何が起こったか、代わりにどこに移動するかを理解できるようにします。
  • <this page> has been moved to <that page>
  • <this document> has been removed because of <the reason>

さらに読むためのリファレンス

• ウィキペディアのポリシーとガイドライン
• Confluence表記ガイド
• Wikiパターン

まず、良いWikiを選択することが重要です。次のいずれかを選択します。

1. よく維持されており、サポートも良好です。
2. ユーザー認証をサポートし、ドキュメントまたは名前空間へのアクセス制御があります。
3. ドキュメントへの変更を追跡し、履歴を提供します。
4. ドキュメントの変更の電子メール通知を許可します。
5. 優れたエディター（できればWYSIWYG）があり、リスト、テーブル、画像のアップロードをサポートしています。

開発チームのWikiに必要な最大のものは、「庭師」、つまりWiki内のドキュメントのレイアウトと構造を決定する責任のある人物です。それはフルタイムの役割である必要はありませんが、庭師は強い英語と物事をうまく説明する能力を持っている必要があります。庭師は、ページの標準テンプレート、命名規則を作成し、必要な名前空間を決定する必要があります。

庭師はコンテンツを作成する責任はなく、その構造を強化します。たとえば、誰かが製品に変更を加えた場合、庭師はWikiに変更を加える責任はありません。ただし、庭師は、変更が確実に行われ、ガイドラインに従って行われることを確認する責任があります（たとえば、個別のリンクされていないページに貼り付けられているだけではありません）。庭師は変更を確認するか、それを他の誰かに委任することができます。

コンテンツを作成する人のニーズではなく、聴衆のニーズを満たすようにWikiを構造化することが重要です。たとえば、ソフトウェア開発専用のUIまたはセキュリティまたはローカリゼーションチームがある場合、それらの情報を別々のセクションに配置しないでください。開発者が見ているのと同じセクションにそれらを置きます。すべてを1つにまとめることで、検索がはるかに簡単になり、物を見落とさないようにし、古いコンテンツをより早く特定できます。

Wikiには考え方の変更が必要です。多くの企業は、それらに強制される情報に慣れています。Wikiを使用すると、情報の利用者は情報を変更できます。これは強く奨励されるべきです（必要であれば報われる）。不正確さが懸念される場合は、変更が行われたときに電子メールで送信するようにレビューアにWikiを設定してもらいます。

開発Wikiには、バージョン管理を処理するための戦略が必要です。バージョン1.0の一連のドキュメントがある場合、バージョン2.0がリリースされるとどうなりますか？バージョン1.0の一部のドキュメントは2.0にも適用できますが、一部が置き換えられる場合があります。2.0のリリース後に1.0のドキュメントに変更が加えられた場合はどうなりますか？

Wikiは成功を測定する何らかの方法を必要とします。何人が使用していますか？彼らは探していたものを見つけましたか？ページの下部にある見苦しい大きな評価とコメントボックスは必ずしも必要ではありませんが、単純な「このページについて人間にメールを送信する」リンクが役立つ場合があります。

最後に、Wikiの使用パターンは時間とともに変化します。標準を定期的に見直して、Wikiのニーズを満たしていることを確認してください。

すべてのプロジェクトのWikiページが同様のテーマに従っていて、誰もがどこにあるかを知っているのは良い考えですが、これは実際には開発者がページを更新しないという問題には対処しません。

開発者がこれらのことを実行して、それを推進し、実行したいという十分な利益を得る方法を見つける必要があります。さもなければ、彼らはそれを彼らがなしでできるもう一つのトップダウンの官僚的負担と見ます。

私はこのような状況にありました。Wikiが完全に混乱していた場所と、非常に体系的で正式な場所の両方です。Wikiの状態は、開発者の興味のレベルに影響を与えませんでした。