仕事、プロセス、環境をどのように文書化しますか？

ウィキ形式を使用していますか？ある場合、どの製品ですか？（MediaWiki、Confluence、Sharepointなど）

知識ベースを作成しましたか？（問題/ソリューション指向の短いドキュメント。）

機能するドキュメントを作成する際にどんな課題がありますか。休暇中に電話をかけられませんか？

私にとっては、ドキュメンテーションの作成に関連する組織の「慣性」がある程度あることがよくあります。仕事をすることができる別の種類の人のようで、他の人ができるように彼らがどのように仕事をしたかを考えて説明してください。

更新

これまでの回答には、

• 合流
• Flexwiki
• フォグバグ
• Mediawiki（fckeditorなどのプラグインを使用）
• 共有ポイント
• TWiki
• Word / Excel / Visio Docs
• 文書化されたスクリプト

編集：監視システムでネットワークを暗黙的に文書化していませんか？Nagiosは、常にネットワークの構造を反映する親ディレクティブの使用を推奨しており、notes_urlディレクティブは、wikiまたは他のブラウザベースのドキュメントにリンクできるように設計されています。そのため、ここで「ドキュメント」は、監視システムの「生きているドキュメント」と、ウィキ内のより詳細なオフラインドキュメントに分割されます。私はNagiosをじっと見つめるのに多くの時間を費やしているので、可能な限り有益なものにするために努力することは理にかなっています。

ツールに関するコメント。

オンラインwikiを試してみましたが、個人的な趣味である可能性のあるいくつかの制限を発見しましたが、ドキュメントの構造が含まれ、最も重大なことにドキュメントサーバーに接続する必要があります。

オフラインまたはオンサイトの場合、接続されていることは深刻な問題です（明らかに、安全なSSL接続などでオンサイトを緩和できます）。

現在の文書化プロセスは次のとおりです。

• 静的HTMLジェネレーター
• マークダウン構文
• 分散バージョン管理システム

ドキュメントの「正式な」レイアウトがあり、メニューの構造（および視覚的なスタイリングなどの関連CSS）を提供します。

静的HTMLジェネレーター

cubictempと他の多くのツールに基づいた社内静的HTMLジェネレーターを使用します：pygments、docutils。

私たち/システム管理者/プログラマーのほとんどは美的に美しいものを知っているが、そのようなものを構築するための調整が完全に欠如しているので、生成されたページは明らかに（いです。

しかし、それは構成ファイル、サンプルスクリプト、pdfなどを含めることができます/それは、それを台無しにするhtmlフォーマットを心配したり、ダウンロードのための「サーバー」でそれを見つける場所を心配する必要はありません。

HTMLでない場合は、フォルダにドロップして、URLリンクを追加します。

HTMLはレイアウトの「潜在的な」構造を提供し、ナレッジ/コンテンツアイテム（およびメニュー、コンテンツのテーブルなどを作成できるなどの基本構造メカニズム）の間の「リンク」も決定的に提供します。 lighttpdであろうと小さなものであろうと、マシン上で小さなWebサーバーを実行するか、ApacheやIISで十分に機能します。

私たちのすべてのマシンは、基本的なhtmlの提供にうんざりしており、十分に機能します。

MARKDOWN構文。

MARKDOWN、Textish、またはreStructuredTEXTの粗悪なバージョンを使用して、「創造的な」ジュースがHTMLを心配することなくドキュメントを作成できるようにします。

また、誰もがお気に入りのエディター（Windowsと* NixでScintillaを使用）を使用し、他のエディターはvi / vimを使用することを意味します。

分散バージョン管理システム。

Gitを使用して、ユーザー間でドキュメントを「配布」します。ああ、バージョン管理機能も使用します。

私たちの主な利点は、サーバーに接続しなくても、また「完成した」作品を公開することなく、すべてのドキュメントの更新に取り組むことができることです。ドキュメントの同じ部分、または異なる部分で作業することも、情報を消費することもできます。

個人的には、Wikiはもちろんのこと、ブログを更新するためにサーバーに縛られるのが嫌いです。Gitは私たちにとってうまく機能します。

ワークフローに関するコメント

ウィキは知識の普及/体系化の「ファッション」のように見えますが、他の場所でコメントされているように、すべてのプロセスを維持するのが難しくなり、チームのニーズを最もサポートし、持続可能なツールの組み合わせを見つけるには時間がかかります。

より良い解決策は、単に発見されたものであり、強制されたものではありません。

私は仕事をしているDokuWikiを使い始めました。

DokuwikiのWebサイトから：

DokuWikiは、標準に準拠した、使いやすいWikiであり、主にあらゆる種類のドキュメントの作成を目的としています。開発者チーム、ワークグループ、中小企業を対象としています。シンプルでありながら強力な構文を使用して、データファイルをWikiの外部で読み取り可能にし、構造化テキストの作成を容易にします。すべてのデータはプレーンテキストファイルに保存されます。データベースは必要ありません。

Dokuwikiは、データベースを必要とせず、セットアップも簡単だったため、実装が最も簡単でした。また、すべてのアカウントを作成するのではなく、既存のActive Directoryアカウントログオンを使用できるようにするアドインモジュールもありました。また、誰がどこに何を投稿したかを確認できる標準的なバージョン管理機能も備えており、必要に応じて簡単に以前のバージョンにロールバックできます。また、カスタマイズ可能なホームページも含まれており、環境に最適なコンテンツの種類を簡単に変更できます。

Doku WikiまたはSharepointを使用して、チャートに収まる他のものを確認します。

Wikiに投稿するのにかなり早く慣れ、構文はそれほど複雑ではありません。情報を非常に簡単に整理し、後で他の人が簡単に見つけられるようにします。

visioを使用して、より明確な説明のためにグラフを作成します（JPEGとしてエクスポート）。

Wikiを使用しています。実際、MediaWikiを使用しています。MediaWikiの上に、Semantic Mediawiki拡張機能がインストールされています。これにより、MediaWikiは実際には、カテゴリ、タイトル、コンテンツなどでクエリできる、緩やかに型付けされたデータベースになります。

たとえば、クラスターFを経由するすべてのネットワークcnameを表示したいとします。する必要があるのは、Special：Askページを使用して[[Category：cname]] [[destination :: cluster_f]]を照会することだけです。 。そして、宛先がcluster_fであるcnameとして分類されたすべてのページを返します。

数百の非常に異なる顧客をサポートしているため、そのドキュメントを中央に配置する（そして、特別なケースがドキュメント化されて全体に結び付けられるようにクロスリンクする）ことは非常に便利です。当然、ドキュメントを保守する必要がありますが、大規模なデータセットを最新の状態に保つためのmediawikiツールキットはすでにかなり成熟しているため、保守には「庭師」のアプローチを採用できます。

適切なプラグインがあれば、Tracはチケットとウィキの組み合わせシステムになります。これにより、チケットがWiki記事にリンクしたり、その逆にリンクしたりするのが簡単になります。

私が好きなプラグインのカップル：

• プライベートチケットプラグイン。Tracは、すべてのチケットとその応答が公開されるバグベースとして構築されています。ITチケットシステムには適切ではありませんが、このプラグインはそれを修正します。
• Trac WYSIWYGプラグイン。それに直面してみましょう、ほとんどの人はあなたを幸せにするためにwikisyntaxを学ぶつもりはありません。これにより、チケットとWikiページの両方に対して「表示されるものが取得するもの」エディターになります。

Tracにはさらに多くのカスタマイズがあります。Tracシステムを好みに合わせてセットアップしてカスタマイズするのは難しくありません！

以前の仕事では、Twikiを使用しました。かなりうまくいきました。

その横に、私はほとんどのタスクを自動化し、スクリプトを文書化する傾向があります（常に熱心ではありませんが、それでも...）。スクリプトの文書化は、それらを設計するプロセスで簡単に行われるため、実際のオーバーヘッドはありません...

両方の組み合わせ（およびスクリプトにバージョン管理を使用）は、かなりうまく機能しました。

JIRA、Confluence、およびWord文書の混合。

知識の制度化

ドキュメントから始めました。次に、それらの一部をSharepointライブラリに保存しました。その後、最近Sharepoint wikiに移動しました。Sharepointのwikiでは、グラフィックのサポートやテーブルなどのフォーマットのサポートに必要なものがいくつか残っていますが、私はWikiの低摩擦アプローチで物事を迅速に更新するのが好きです。テキストには問題ありません。組み込みのエディターでは、基本的なHTMLの書式設定と順序付き/順序なしリストが許可されています。Sharepointには、他の低コストの代替品があります。

また、ヘルプデスクソフトウェアであるNumaraのTrack-Itには、サポートチケットに関する非公式のナレッジベースがあります。完全ではありませんが、機能します。

スタッフに制度化されたKnowlegeを使用させる

知識を制度化することは戦いの一部にすぎないとの評価に同意します。あなたの組織と人々が「最初に研究し、2番目に尋ねる」ことに慣れていない場合、古い方法が優勢であることがわかります。あなたの隣の人は自分で検索するよりも。

これに対処するには、変更管理が必要になります。ほんの小さなチーム以上のものに影響を与えるほとんどの成功した変更イニシアチブのように、それは経営者の支持とサポートを持つのに役立ちます。本当に2つの方向に新しい動作を偽造する必要があります。誰かが知識をキャプチャする必要があり、人々はそれを使用する必要があります。さらに難しいのは、人々もそのデータを最新に保つ必要があるということです。

いくつかのアイデア：解決済みのチケットと問題は、クローズと見なされる前にナレッジベースまたはwikiに文書化する必要があることを示す正式なポリシーの形で奨励する必要があるでしょう。さらに、通常質問されるナレッジリーダーは、常に要求に応じて回答を提供するだけではありません。彼らは人々をウィキに誘導し、最初にチェックすることに慣れる必要があります。もう1つは、ユーザーがセルフヘルプのためにデータを利用できるようにすることです。これにより、技術スタッフがやり直す必要がある別の項目になる前に問題を解決できる可能性があります。

ヘルプデスクシステムがStackOverflowやServerFaultに類似したシステムを備えていると便利です。質問を入力すると、検索エンジンは類似のアイテムを見つけて提供するので、ユーザーは質問を送信する前でもそれらを見ることができます。

作業の最後の2つの場所では、Wikiドキュメントとして簡単に作成できない特定のドキュメント（DRPや1回限りのアップグレード計画など）を含むドキュメントライブラリとともに、SharepointのWikiを使用しました。これらのドキュメントには、Wiki内からのリンクがありました。Wikiにはこの分野で多くの利点があります。多くの人が編集できること、バージョン管理機能が組み込まれていること、簡単に検索およびアクセスできることなどです。メモやアイデアをすばやく書き留めるには、OneNoteまたはホワイトボードを使用します。

以前にフォーラム形式（Lotus NotesとMS Sharepointの両方）でいくつかのナレッジベースを作成しましたが、特定の問題がすでに解決されたかどうかを確認するためにそれらを参照する人はほとんどいません。このようなソリューションは、非常に強力で効果的な検索エンジンを備えた初日からのものでなければなりません。

休暇中に使用できるドキュメントを作成する場合は、親の1人に指示しようとしているように書きます。これは100％確実なわけではありませんが、時には役立ちます。誰がそれを読んでいるかによって異なります。

Sharepointはいいですね。

検索機能には、ほとんどすべての種類のドキュメントのインデックスを作成する機能があり、ドキュメントの検索が非常に簡単になります。

テンプレートを作成することもできます。これにより、たとえば、構築する各サーバーの標準情報シートがある場合、作業が簡単になります。

また、ドキュメントをバージョン管理して、ドキュメントの変更の監査履歴を取得することもできます。

さらに、ドキュメントライブラリに含まれるファイルには、Web、Outlook、またはunc共有を介してすぐにアクセスできます。

MediaWiki（fckeditor を使用）を数年間使用しましたが、画像（スクリーンショット）の処理が簡単であればいいと言わざるを得ません。また、検索機能を持つことは不可欠ですが、MediaWikiの検索ではページを見落とすことがよくあります。おそらく、それは単により良い検索を学ぶことの問題です（これは、他の人があなたの仕事をするための簡単な方法を持つという目的を打ち負かします）

現時点では、すべてをMS Sharepointに移行することについて話し合っていますが、必ずしもWikiに移行するわけではありません。Sharepointは、Wikiの利点のいくつかを無効にする方法で完全なドキュメント検索を行うことができると思うので、これがどこに行くのかを見ていきます。

（ただし、現在のすべてのドキュメントを移植するプロセスを楽しみにしていない:)）

Wikiを使用しています。構文は慣れるまで少し時間がかかりましたが、私たちが使用している構文（twiki）はデータをテキストファイルとして完全に保存します。これにより、災害発生時に簡単に読み取ることができます。どこにでも復元でき、grepを介してコマンドラインから検索し、好きなテキストエディターで読み取ることができます。

すべてのサーバーにはページがあり、変更管理情報、起動/シャットダウン、構成に関するメモ、DNS、ファイアウォール、資産情報のサブページの標準コレクションがあります。

Sharepointサービスのあるバージョンに移行する準備が整いました。3台のサーバーにまたがっており、フォルダーの数を知っているワードドキュメントの混合物から私たちを解放しようとしています。現在、私たちは、そこに記述されているドキュメントへのハイパーリンクを含む大規模なExcelスプレッドシートを持っています。

最善の方法ではありませんが、会社が始まったとき、彼らは内部ドキュメントの処理方法を計画せず、各グループに任せて、適切と思われる独自のドキュメントのソートおよび保存方法を決定しました。現在、私たちは統合されたシステムに統合しようとしています。これは、SharePoint製品の1つになります。

私が働いているNGOでは、重要な手順のためにフォルダに配置されたテキストファイルを使用しています。個人的に私はそれが私だ、木のディレクトリに散在テキストファイルの知識ベースを使用してきたシステム管理者/ Web開発者のハイブリッドとしてMemexと私はそれにほぼすべて（個人、仕事、など）を書き留めます。このスキームは、テキスト処理用の本物のスイスアーミーナイフであるJeditを使用して管理するのが非常に簡単で、アウトラインプラグイン、コードの折りたたみ、ハイパーサーチ機能が不可欠であることがわかりました。これらはすべて、rsyncによってsshアクセス可能なリモートサーバーに安全にバックアップされました。

それをMakelink Firefox Extensionと組み合わせると、完璧なブックマークマネージャーができます。

ドットネットおよびオープンソースであるflexwikiを使用します。

えーと... Fogbugzはどうですか？:)

コンテンツにはScrewTurnを使用し、ドキュメント/画像を保存するにはSharePointを使用しています。

ここにはいくつか興味深いものがあります -私は金庫のパスワードに関するものが好きです。

テキストファイルの組み合わせを使用して、grepですばやく検索します。さらに詳細なドキュメント（Visioダイアグラムなど）のより整理されたコレクションのためのSharePoint。

Google Apps（Enterprise）クライアントとして、Googleサイトのウィキ「フレーバー」を活用しています。使いやすく、管理者や開発者から大きな支持を得ています。

私は別の質問に答える前にこの質問を見ませんでしたが、ここに行きます。

多くのツールと方法を使用します。

• インフラストラクチャコンポーネントおよびソフトウェアの機能仕様。
• 2つのConfluence Wiki。1つは社内ドキュメント（ポリシー、手順、内部インフラストラクチャ、ITなど）用で、もう1つはオープンソースソフトウェア製品用です。
• RSpecおよびCucumberテスト。私たちのソフトウェアは主にRubyで書かれており、BDD / TDDを実践しているので、仕様テストは実際のコードとドキュメントを駆動します。
• インラインコードのドキュメント。コードコメントではRDocマークアップを使用します。
• 宣言的な構成管理（Chef）。すべてのサーバーはChefで管理されます。Chefは、レシピと料理の本の説明的なリソースを通じて「自己文書化」します。

Confluenceが気に入っているのは、非常に柔軟で強力であり、機能が充実しているだけでなく、好きなチケット管理ソフトウェアであるJiraと連携しているためです。

私が働いていた以前の会社では、さまざまなツールと方法を使用してきましたが、多くはすべてのために単一の包括的なリソース（Wikiなど）を使用しようとしました。それに関する問題は、そのトピックをカバーするのに適したものではない単一のツールでさまざまなトピックを文書化することです。つまり、情報を移行するのが難しいため、多くのものはまったく文書化されません。Unix / Linuxオタクとして、各タスクには特定のツールが必要であり、そのツールはそのタスクに非常によく適合するはずだと思います。

この質問は非常によくの複製で、この1と私はそこに私の答えを動かしました。

私は会社のほとんどのドキュメントを作成し、ここで仕事を始めたときに確立された形式は、編集可能なオリジナルのMS Wordであり、読み取り専用の一般リリース用にPDFにエクスポートされました。ドキュメントを更新しているのは1人だけで、通常はその人が私であるため、管理者は変更の必要性を認識していません。

コードレビューに「ピアレビュー」拡張機能を使用しながら、バグと今後のタスクをTracで文書化し始めました。コラボレーションが簡単で、操作も簡単なため、チームから大きな支持を得ています。他の少数のチームメンバーは、仕様、テスト手順、およびマニュアルとのさらなるコラボレーションを開始したいという要望を表明したため、マニュアルなどの公開ドキュメント用のPDFにエクスポートされたDocBook / XMLと、仕様やテスト手順。

私の考えでは、ドキュメント形式を選択する際の最大の問題は次のとおりです。

1. 簡単に作成できますか？
2. 保守は簡単ですか？
3. 他の誰かが書いた場合、維持するのは簡単ですか？
4. 手間をかけずに他の形式にエクスポート/変換できますか？

1-3は私の生活を楽にし、狂気にならずに迅速にドキュメントを作成するために重要です。フォーマットは絶えず変化するため、4つ目は顧客側で最も重要だと思います。Microsoft Word 2003形式は永遠に続くものではなく、現在のPDFの実装でもありません。OSやドキュメントリーダーの選択に関係なく、すべてのお客様がドキュメントを読むことができるようにする必要があります。

SemanticMediaWikiを含むさまざまなプラグインでMediaWikiを使用します。SWikiは、MediaWikiのインストールを、自由にクエリできる大きな自由形式のリレーショナルデータベースに変えるため、優れています。ウェブサイトがどのサーバーにあるかを知る必要がありますか？そのページにアクセスしてください。サーバーでホストされているWebサイトを知る必要がありますか？クエリを実行すると、各Webサイトのページの適切なタグに基づいてページ名が選択されます。

私が使った文書システムではなく、私が使ったのを見て、とても良いと思うもので答えます：http : //stackexchange.com/

stackexchangeは、serverfaultの下で実行されるQ＆Aプラットフォームです（技術的にはまったく同じではありませんが、ここでの目的のために、同じであると想定できます）。

Fogbugz はそれを使用します。

私がこれらの引用を見つけたFogbugzの従業員からの興味深いブログ投稿があります：

製品仕様以外のあらゆる目的で、企業のウィキとディスカッションフォームは致命的な打撃を受けたと思います。

...

FogBugz.StackExchange.comをサポートプラットフォームとして使い始めたので、同じ質問に2回答えたことはありません。非公開のQ＆Aに使用する内部SEサーバーもあり、同じ原則が適用されます。

彼らは、顧客向けのナレッジベースと内部ナレッジベースにstackexchangeを使用しています。

このような知識交換Q＆Aプラットフォームが企業のwikiに取って代わるかどうかを確認したいと思います。

以前の雇用主では、フォルダーにまとめて収集されたWord、Excel、およびVisioファイルを使用していました。すべてのハードコピーが机のバインダーに保管されていました。IT担当者は私だけだったので、他の人が情報にアクセスする必要はほとんどありませんでした。

現在の雇用者では、Exact SoftwareのMacola ESを使用していますが、組み込みのドキュメントエディターを使用するよりも、Wordでドキュメントを作成し、添付ファイルとしてMacolaにアップロードすることを好みます。

私の職場では、Windows開発サーバーの1つにScrewTurn Wikiをドロップし、SQL Serverに接続しました。それは本当にうまく機能し、素早く動作し、主にドキュメント作成の邪魔になりません。展開されてから2週間で、約60ページの情報が既に追加されており、チーム（10人まで）専用です。

これまでのところ、現在および過去のプロジェクトに関する情報をそこに保持し、最初からビルドする方法、URL、およびチームの新しい開発者向けの他の重要な情報など、アプリケーションに関する情報の追加を開始しました。

Wikiでお気に入りのページの1つは、ツールとライブラリのページです。そこで、私たちはよく使用するお気に入りの生産性ツールとライブラリに関する情報を追加し始めました。その例は、Windowsでのテキスト検索用のgrepWinです。

利用可能なWikiの全範囲をチェックして、目的の使用法、機能、および展開環境に適したものを見つけることをお勧めします。ScrewTurnを選択した理由は、使いやすいからです。また、ローカルのWinServerにはYMMVの空きスペースがたくさんありました。

場合によっては、ConfluenceをWikiおよびドキュメントの共有ポイントとして使用しています。この情報を本当に広く共有する必要がある場合や、ドキュメントを非常に頻繁に編集および更新する場合はさらに重要なことは、オンラインWiki形式が好ましいと考えています。だから、ナレッジベースの記事はwikiに入れたほうがいいと思う。

現在、ネットワーク上に散らばっているさまざまなドキュメントから2つの場所に情報を移動しています。

1. イントラネットで利用可能なウィキ
2. そのサーバーの/ rootディレクトリ内の特定のサーバーに関連する情報のコピー。

ネットワーク図の場合は、ネットワークメモ帳。

また、whatを記録するときに、何かがそのように構成されている理由を記録することを忘れないでください。これは、良いアイデアのように見えるアイデアが間違いに変わるのを防ぐのに役立ちます。

MediaWikiは手始めが遅いことがわかりましたが、IT以外の人がコメント、変更、編集などを追加するのがいかに簡単かという風になれば、それは不可欠になりました。開発者は、内部ドキュメント、施設部にそれを使用しています。通知などを投稿するために。それは単なるIT文書化ツールを超えて成長しています。