開発者に Wiki を使用してもらう [終了]

https://stackoverflow.com/questions/15871

08-06-2019
|

質問

私は、さまざまなチームがある程度の重複を伴う独自のモジュールに取り組む複雑なアプリケーションに取り組んでいます。少し前に、私の指示もあって、Mediawiki インスタンスをセットアップしました。私は人々にそれを実際に使ってもらうのが大変で、ましてや貢献するのは大変です。

情報を共有することには多くの利点があると感じています。少なくとも車輪の再発明の回数は減るかもしれない。

Wiki はあまり構造化されていませんが、必要なものを検索できる限りは問題ないと思います。

ヒントはありますか？

解決

私が示したように前に, Wiki は非常に整理されていません。

ただし、それが開発者からの唯一の主張である場合は、簡単なインデックスページを作成し、それを更新し続けるためにある程度の労力を費やしてください (自分で行うか、人々に自分の投稿をインデックスにリンクするよう依頼してください)。そうすれば、Wiki はすべての作業に関する非常に優れた、非常に包括的なドキュメントのコレクションに成長する可能性があります。

他のヒント

いくつかのヒント：

誰かが本当に Wiki に載せるべき情報を電子メールで送信する場合は、そのトピックのページを作成し、電子メールに記載した内容を追加します。次に、「その情報はありがとう。今後見つけやすくするために、ここの Wiki に入れておきました。」と返信します。

同様に、共有する必要がある情報があり、Wiki に記載する必要がある場合は、Wiki に置き、他の人に電子メールを送信するのではなく、その情報へのリンクを記載した電子メールを送信するだけです。

人々に情報を求めるときは、そのようなドキュメントを Wiki に置くことがデフォルトまたは標準であると考えられるように表現してください。「wikiで調べたんですが見つかりませんでした。その情報はもう載せましたか？」

あなたが「Wiki チャンピオン」である場合は、他の人がその使い方を知っていることを確認してください。「新しいページの作成方法はもう説明しましたか?」

サイドバーを編集して、自分の作業に関連するものであることを確認します。

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

トップページに {{Special:NewPages/5}} のようなものを配置したり、最近の変更を表示したりして、アクティビティを確認できるようにします。

数日または毎週ごとに「最近の変更」を覗いてみましょう。誰かが促されずに情報を追加していることに気づいたら、その人にメールを送信するか、立ち寄って少し褒めてください。

私たちはしばらくの間、何らかの形で Wiki を使用してきましたが、人々が参加するまでには時間がかかります。しばらくの間、記事を書くのは自分だけになるかもしれませんが、最終的には他の人も参加してくれるので、我慢してください。

誰かがプロジェクトに関連する情報を含む電子メールを送信した場合は、Wiki の方向を有益に誘導し、それを続けてください。ヒントが得られるはずです。

私たちは SharePoint ポータルを持っており、そこから Wiki を使用しています。独自のブランディングでウィキをカスタマイズして、「部分的に見える」ようにしました。これがウィキの普及率向上に役立っていると実感しています。

Wiki は電子メールよりもさらに非公式であることを全員に認識してもらいます。なぜなら、Wiki に追加するものはすべて過剰分析されるのではないかと人々が考えるかもしれないという「恐怖要素」が存在するからです。

これまでの答えのほとんどは的を射ていると思います。自分で取り組めば取り組むほど、有益な情報の量は膨大になるため、ゆっくりと、しかし確実に、人々は自然にそれを使い始めるでしょう。

使用できる他のアプローチは次のとおりです。誰かが他のチームメンバーにプロジェクトについて質問するたびに、通常どおり質問に答えるだけでなく、その回答を Wiki のセクションに追加する必要があることを提案します。これにはさらに数分かかるかもしれませんが、次回誰かが同じ質問をするとき (必然的にそうなります) に Wiki を参照することで時間を節約できることになります。これにより、人々が最初の情報源として Wiki を使い始め、全体的な普及が促進されるはずです。

開発者に使用する動機がないことを強制することはできません。残念ながら、Wiki はドキュメントのようなものです (まあ、実際には Wiki はドキュメント) は、開発者にとって「クールな」価値があることはほとんどありません。それに、彼らはすでに開発作業に没頭しています -- Wiki のことで彼らの邪魔をすることが本当にできるでしょうか?

そうは言っても、Wiki を推進した人 (たとえば、あなた) が主に Wiki を更新する責任を負うべきであり、もしあなたが真剣に取り組んでいるのであれば、本当に多くの労力を費やさなければなりません。

ff も試してみてください:

あなたが言うには、あまり構造化されていない -- 多くの人が、構造化されていない (検索や閲覧が難しい) Wiki に興味を持たなくなります。それで、最初にそれを修正できるかもしれません
おそらく、主任開発者/プロジェクトマネージャーに、彼らにとって問題となっているものを入力するよう依頼することができます。特定のプロジェクトのコード規則や API 設計など
模範を示す:宗教的な文書 あなたの システムの一部。前例を作ると、他の人も同じようにするようになる可能性があります

Wiki を使用するというアイデアを開発者に売り込みます。いくつかのメリットを特定したので、それを開発者と共有します。そこから何か価値のあるものが得られることがわかれば、彼らはそれを使い始めるでしょう。

メリットの例 Wikiとは

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

私は販売を行ったり、トレーニングセッションを行ったりしました。WYSIWYG 編集や、Word や Outlook から書式設定されたテキストを貼り付ける機能がないことに嫌悪感を抱く人もいると思います。これらを回避するツールがあることはわかっていますが、依然として障壁となっています。

特定の領域のログを記録するために Wiki が使用されている領域がいくつかありますが、それらを更新する人はそれ以外のことは何も行っていません。

便利な脳の拡張機能として機能するため、私はウィキを使用して自分の専門分野を文書化します。新しい開発を開始するときは、開発の進行に合わせて拡張できるアイデアのメモ帳として使用します。

たとえ義務化されなくても、経営陣が声高にサポートしてくれると助かります。

私は人々にそれを実際に使ってもらうのが大変で、ましてや貢献するのは大変です。

人々に Wiki に貢献してもらう最も簡単な方法の 1 つは、実際に Wiki に適した方法でコンテンツを提供してもらうことです。そのため、通常のコミュニケーションチャネル (ニュースグループ、メーリングリスト、フォーラム、問題追跡ツール、チャット) を使用して投稿したものはすべて、基本的に Wiki に含めるのに適しています。

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

これは実際よりも複雑に聞こえますが、主に質問と回答を一般化して、必ずしも会話の一部ではなく、独立した形で理解しやすく、意味があり、役立つものにすることが目的です。

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

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

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

こんにちは、gitクローンgit：//を使用するだけです。

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

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

私が言いたいのは、プロジェクト内のほとんどのディスカッションは、最終的には簡単に文書化できるし、そうすべきだということです。このような考え方をすると、ドキュメントは実際にかなり急速に成長する可能性があります。有益な情報は理想的には Wiki に含めるのに適した方法で提供されるべきであるということを人々に覚えてもらうだけで済みます。

私は、オープンソースプロジェクトがこのアプローチをある程度使い始めた例を何度か目撃しました。一部の人々 (主に新規ユーザー) は、答えがあまり個人的ではないと不満を言いましたが、他の人々は単にそのような議論を監視しているだけであり、ドキュメントの本体は着実に増加していました。そのような回答をウィキにコピーアンドペーストし始めました。

基本的に、これは人々に Wiki に貢献してもらうための最も簡単な方法の 1 つであり、人々が実際にウィキを使用する必要はありません。彼らに必要なのは考え方の転換だけです。

開発者が依然として「実際の」ドキュメントを維持する必要がある場合 (s.a.Word ドキュメントなど)、それを Wiki 上で有意義に複製する方法は見当たりません。

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

私の現在の顧客が行ったことは、これらすべてを Wiki に移動することです。だから私は一度だけ文書化します、そしてそれを実行しますの上ウィキ。

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

もう 1 つの有効な解決策 (私見) は、ドキュメントをソースと一緒に Subversion に保存することです。ただし、結合システムはリッチテキストなどに対応できる必要があります。同じように。そのための解決策が存在するかどうかはわかりません (HTML または LaTex を使用する以外に、実際には悪い選択ではありません)。

「粘着性のある」アイテムを見つける (サブ 3 ページ)docs/diagrams/etc) チームが繰り返し作成していると思われるものを Wiki に投稿します。全員が Wiki にアクセスでき、Wiki が存在することを認識していることを確認してください。可能であれば、通知メカニズムを設定してください。運が良ければ、次回アクセスする必要があるときは、バージョン管理やマシンからアクセスするのではなく、Wiki にアクセスする必要があります。それでも使用しない場合は、チームに Wiki を実際に使用するのに十分な余裕があるかどうかを確認してください。彼らの消極的な背景には、微妙な問題が潜んでいる可能性があります。

のアドバイスを見てください。 http://www.ikiw.org/ Wiki を成長させましょう

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

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

さらに、すでに Mediawiki の世界に入っている場合は、以下を参照するとよいでしょう。セマンティックメディアウィキ. 。データに意味論的なタグを付けることで、データの編成を別のレベルに引き上げることができます。それ自体には大きな意味がないことは承知していますが、(たとえば) 検索から返されるデータの関連性を大幅に向上させることができるということは言えます。一見の価値ありです。

ここで一般的に良いアドバイスがあります。付け加えておきたいのですが：

あなたは本当に必要ある チャンピオン - 誰かがこれを開発者や管理者に（自分自身を無視して）押し付けている強引 - それは挑戦です!)、可能な場合はサポートとチュートリアルを提供します。また、この人は同僚である必要があり (つまり、離れた IT 部門の誰かではなく、開発者仲間である必要があります)、本当に顧客中心である必要があります。要求に応じて変更を加える準備ができています。
変化について言えば、ここにいる人たちはこう言います。 ウィキは構造化されていない. 。私は同意しません。MediaWiki インストールは、特に 2 つの拡張機能を備えたカテゴリを使用して構造化されています。警告カテゴリなし (ページを保存するときにユーザーにカテゴリの追加を要求するため) およびカテゴリツリーすべてのカテゴリがどのように組み合わされるかを示します (これはサイドバーからリンクできます)。このしきい値を低く保つ方法については、さらにヒントがありますので、ご興味があればご覧ください。

ライセンス： CC-BY-SA と帰属

所属していません StackOverflow