documentation - 開発者にwikiを使用させる

Question

私は、さまざまなチームがある程度の重複を持って独自のモジュールで作業する複雑なアプリケーションに取り組んでいます。しばらく前に、Mediawikiインスタンスをセットアップしました。貢献するどころか、実際に使ってもらうのは大変です。

情報を共有することには多くのメリットがあります。それは少なくとも私たちが車輪の再発明をする時間を減らすかもしれません。

wikiはあまり構造化されていませんが、必要なものを検索できる限り、それが問題になるかどうかはわかりません。

ヒントはありますか？

score 26 · Accepted Answer

いくつかのヒント：

誰かが電子メールで wiki に載せるべき情報を送信した場合はいつでも、そのトピックのページを作成し、電子メールに入力した内容を追加します。次に、「その情報をありがとう。後で簡単に見つけられるように、ここの wiki に入れておきました。」と返信します。

同様に、共有する必要がある情報が wiki にある場合は、そこに置き、メールを送るのではなく、そこへのリンクを記載したメールを送信します。

人々に情報を求めるときは、そのようなドキュメントを wiki に置くことがデフォルトまたは標準と見なされるように、次のように表現してください。

あなたが「Wiki チャンピオン」である場合は、他の人がその使用方法を知っていることを確認してください。

サイドバーを編集して、作業に関連するようにします。

ナビゲーションを容易にするために、関連するページで「ナビゲーションボックス」スタイルのテンプレートを使用します。

{{Special:NewPages/5}} のようなものをフロントページまたは最近の変更に配置して、人々が活動を確認できるようにします。

数日または数週間ごとに最近の変更をのぞいてみてください。だれかが促されずに情報を追加しているのに気づいたら、メールを送るか、立ち寄って少し褒めてあげてください。

score 8 · Accepted Answer

前に述べたように、Wikiは非常に整理されていません。

ただし、それが開発者からの唯一の議論である場合は、簡単なインデックスページを作成して最新の状態に保つために、ある程度の努力を払ってください（自分で行うか、投稿をインデックスにリンクするように依頼してください）。そうすれば、Wikiは、すべての作業に関する非常に優れた、非常に包括的なドキュメントのコレクションに成長する可能性があります。

score 6 · Accepted Answer

私たちはしばらくの間、何らかの形でwikiを使用してきましたが、人々が参加するまでにはしばらく時間がかかります。しばらくの間、あなただけが記事を書いていることに気付くかもしれませんが、それに耐えれば、最終的には他の人が参加するでしょう。

誰かがプロジェクトに関連する情報を含む電子メールを送信した場合は、wikiの方向に向けて、それを続けてください。ヒントを得る必要があります。

私たちはSharePointポータルを持っており、そこからwikiを使用しています-「一部に見える」ように独自のブランドでカスタマイズしました-これがその取り込みを改善するのに役立ったと本当に感じています。

ウィキは電子メールよりもさらに非公式であることを全員が認識していることを確認してください。ウィキに追加したものはすべて過剰に分析されると人々が考える「恐れの要因」があるためです。

score 5 · Accepted Answer

これまでの答えのほとんどは的を射ていると思います。自分でプラグを抜くほど、有用な情報の本体が大きくなるので、ゆっくりですが確実に人々はそれを使い始めるでしょう。

使用できる他のアプローチは次のとおりです。誰かが別のチームメンバーにプロジェクトについて質問するたびに、通常どおり質問に回答する必要があることを提案しますが、Wikiのセクションにも回答を追加します。これには数分余分にかかる場合がありますが、次に誰かが同じ質問をするときに（必然的にそうなります）、Wikiをポイントすることで時間を節約できます。これは、次に、人々がWikiを最初の情報源として使い始め、全体的な理解を助けるのに役立つはずです。

score 4 · Accepted Answer

開発者に、使用するインセンティブがないことを強制することはできません。残念ながら、ドキュメントのようなwiki（実際にはwikiはドキュメントです）が開発者にとって「クールな」価値を持つことはめったにありません。その上、彼らはすでに開発作業に深く関わっています-あなたは本当にウィキで彼らを悩ませることができますか？

そうは言っても、ウィキをプッシュした人（たとえば、あなた）が主にウィキの更新に責任を持つべきであり、あなたがそれについて真剣に考えているなら、あなたは本当にあなたのために多くの仕事を切り取られるでしょう。

ffを試すこともできます：

あなたが言うように、それはあまり構造化されていません-多くの人々は、構造化されていない（検索/閲覧が難しい）ウィキをオフにします。だから多分あなたはそれを最初に修正することができます
たぶん、リード開発者/プロジェクトマネージャーに、彼らにとって問題となるもの、たとえば特定のプロジェクトのコード規則やAPI設計などを入力するように依頼することができます。
例を挙げてリードする：システムの自分の部分を忠実に文書化します。先例を設定すると、他の人にも同じことをするように促すことができます

score 3 · Accepted Answer

wikiを使用するというアイデアを開発者に売ります。いくつかの利点を特定し、それらを開発者と共有します。彼らがそれから何か価値のあるものを得ることができるのを見ることができれば、彼らはそれを使い始めるでしょう。

Wikiとは何かの利点の例

簡単なアイデアや長いアイデアを書き留めるのに適しています。正式な執筆と編集のための時間を増やすことができます。
ドキュメントを電子メールで送信せずに即座に共同作業を行い、グループの同期を維持します。
Web接続があればどこからでもアクセスできます（Webブラウザのテキストフォームに書き込んでもかまいません）。
すべてのページリビジョンが保持されるため、アーカイブ。
エキサイティングで、即時で、力を与える-誰もが発言権を持っています。

score 2 · Accepted Answer

私はいくつかの販売を行い、いくつかのトレーニングセッションを実行しました。WYSIWYGの編集機能がなく、WordまたはOutlookからフォーマットされたテキストを貼り付ける機能がないために、一部の人は気を失っていると思います。これらを回避するためのツールがいくつかあることは知っていますが、それでも障壁です。

ウィキが特定の領域を記録するために使用されているいくつかの領域がありますが、それらを更新する人々はそれで他に何もしていません。

便利な脳の拡張機能として機能するかどうかに関係なく、ウィキを使用して自分の専門分野を文書化します。新しい開発を始めるとき、私はそれを、それが進むにつれて拡張できるアイデアのメモ帳として使用します。

それが義務化されていなくても、経営陣がそれにいくらかの声のサポートを与えるならば、それは助けになるでしょう。

score 1 · Accepted Answer

開発者がまだ「実際の」ドキュメント (Word ドキュメントなど) を維持する必要がある場合、それを Wiki で意味のある形で複製する方法はないと思います。

人が二度書くのは意味がない
複製されたデータは、すぐに同期しなくなる傾向があります。

私の現在の顧客が行ったことは、これらすべてを Wiki に移行することです。そのため、私は 1 回だけ文書化し、Wiki で行います。

これは大丈夫です。Wiki での作業は Word での作業よりも面倒ですが、少なくともドキュメントはオンラインであり、他のユーザーはそれを組み合わせて使用できます。

別の実用的な解決策 (imho) は、Subversion でソースと一緒にドキュメントを保存することです。ただし、マージシステムはリッチテキストなどにも対応できる必要があります。そのための解決策が存在するかどうかはわかりません（HTMLまたはLaTexを使用する以外は、実際には悪い選択ではありません）。

score 1 · Accepted Answer

人々に実際に使ってもらうのはもちろん、貢献するのも難しい仕事です。

ウィキに貢献してもらう最も簡単な方法の 1 つは、ウィキに適した方法でコンテンツを提供してもらうことです。、チャット) は、基本的に wiki に含めるのに適しています。

他の人 (ユーザー/ボランティア) がそのようなコンテンツを簡単に取得して wiki に載せることができるようにします。

これは実際よりも複雑に聞こえますが、主に質問と回答を一般化して、必ずしも会話の一部ではなく、スタンドアロンの方法で理解しやすく、意味があり、役立つようにすることです。

たとえば、次のような質問です。

git でリモートリポジトリのクローンを作成するにはどうすればよいですか ???

次のように答えることができます。

こんにちは、git clone git://... を使用してください。

ただし、質問には、あまり個人的なスタイルで回答することもできます。

git リポジトリのクローンを作成するには、git に clone パラメータを使用する必要があります: git clone git://....

私が言おうとしているのは、プロジェクト内のほとんどの議論は、最終的にドキュメントにするために簡単に使用できるし、使用する必要があるということです。この種の考え方で、ドキュメントは実際にはかなり急速に成長する可能性があります。有用な情報は理想的には Wiki に含めるのに適した方法で提供されるべきであるということを人々に覚えてもらう必要があるだけです。

私は、オープンソースプロジェクトがこのアプローチをある程度使用し始めたいくつかの例を目撃しました。一部の人々 (主に新しいユーザー) は、回答があまり個人的なものではないと不満を述べていましたが、ドキュメントの本体は着実に増加していました。そのような応答を wiki にコピー/貼り付けし始めました。

基本的に、これは人々に wiki に貢献してもらうための最も簡単な方法の 1 つであり、実際に自分で使用する必要はありません。彼らに求められる唯一のことは、考え方を変えることです。

score 0 · Accepted Answer

チームが何度も作成しているように見える「付箋」アイテム（サブ3ページのドキュメント/図など）を見つけて、wikiに投稿します。誰もがウィキにアクセスでき、そこを知っていることを確認してください。可能であれば、通知メカニズムを設定してください。運が良ければ、次にアクセスする必要があるときに、バージョン管理やマシンからそれを掘り下げるのではなく、wikiにアクセスする必要があります。それでもうまくいかない場合は、チームが実際にwikiを使用するのに十分な余裕があるかどうかを確認してください。微妙な問題が彼らの不本意の下にある可能性があります。

score 0 · Accepted Answer

ここで一般的に良いアドバイス。追加したい：

あなたは本当にチャンピオンを必要としています-誰かがこれを開発者と管理者にプッシュし（プッシュすることなく-それは挑戦です！）そして可能な場合はサポートとチュートリアルを提供します。この人はまた、ピア（つまり、リモートIT部門の誰かではなく、仲間の開発者）であり、実際に顧客に焦点を合わせている必要があります。つまり、要求されたときに変更を加える準備ができている必要があります。
変更について言えば、ここの一部の人々は、ウィキは構造化されていないと言います。同意しません。MediaWikiのインストールは、カテゴリを使用して構成されています。特に2つの拡張機能があります。WarnNoCategories（ユーザーがページを保存するときにカテゴリを追加する必要があります）とCategoryTreeで、すべてのカテゴリがどのように組み合わされているかを示します（これはサイドバーからリンクできます）。興味があれば、この低いしきい値を維持するためのヒントがあります。

score 0 · Accepted Answer

0

http://www.ikiw.org/でアドバイスをご覧ください。

于 2008-10-02T03:08:01.383 に答える

score 0 · Accepted Answer

ここで提供されている優れたアドバイスのいくつかに追加するだけです...

6 ～ 24 か月の範囲で主に政府との契約作業を行う小さな会社の開発者として、私の時間は開発とステータスレポートの作成に分けられることがよくあります (ドキュメントの作成と同じくらい、さらに悪いことに!) wiki のおかげで、整理されていない考えやメモを書き留めることができ、レポート作成の苦痛が大幅に軽減されました (苦痛が減ったわけではありませんが、それでもなお改善されました)。

さらに、既に Mediawiki の世界にいる場合は、SemanticMediawikiを参照してください。意味的にタグ付けすることで、データの編成を別のレベルに引き上げることができます。それ自体はあまり意味がないことはわかっていますが、たとえば、検索から返されるデータの関連性を大幅に向上させることができると言えます。それは間違いなく一見の価値があります。

documentation - 開発者にwikiを使用させる

13 に答える 13

Related

Reference