明白な答えは「内部ウィキ」です。ソフトウェアのドキュメントに使用される wiki の長所と短所は何ですか? 他の提案はありますか？ソフトウェアのドキュメントには何を使用していますか?
Loren Segal - 残念ながら、ソース コードのコメントから情報をコンパイルするドキュメント ツールはサポートされていませんが、技術ドキュメントを保存する最良の方法であることに同意します。私の質問は、sysadmin タイプからユーザー ドキュメントまで、あらゆる種類のドキュメントに関するものでした。
7214 次
8 に答える
7
これは非常に自由回答の質問であり、多くの要因に依存します。
一般的に言えば、優れたドキュメント生成ツール (javadoc、doxygen、MS の C# など) を備えた言語を使用する場合は、メソッドの上にドキュメントを記述し、ツールにページを生成させる必要があります。利点は、テキストのソースをコードと一緒に保持できることです。つまり、テキストは論理的に正しい場所に整理され、メソッドの動作を変更するときに簡単に編集できます。
適切なドキュメント ツールのサポートがない場合、またはソース コードにアクセスできない場合、wiki は悪い考えではありませんが、上記の 2 番目の選択肢です。
注: ここでは、コードのドキュメントについてのみ説明しています。他のアーティファクトは明らかにコードと一緒に保存することはできません.wikiはそれらのドキュメントを置くのに最適な場所です. または、CMS を使用している場合はdocs/、リポジトリ経由で編集できるように、テキスト/pdf/その他のファイルとしてフォルダーにコミットするだけです。利点は、リポジトリが移動された場合にリポジトリにとどまるのに対し、Wiki は移動しないことです (必然的に)。
于 2008-09-19T03:55:29.337 に答える
3
道具は重要ですが、魔法の道具を探すのに行き詰まらないでください。私が見つけたツールには、「目に見えない小さなエルフを使って魔法のようにすべてを文書化する」チェックボックスがありません。:-)
ウィキは問題なく動作します。またはシェアポイント。またはGoogleドキュメント。または、SVN リポジトリを使用することもできます。本当に必要な場合は、ペン、便箋、およびファイル キャビネットでそれを行うことができます。(本当にオススメしません！)
非常に重要な鍵は、組織全体で賛同を得る必要があるということです。多くのショップで起こっていることは、Sharepoint のような優れたソリューションに多くの時間とお金を費やしてから、誰もがそれを約 2 週間熱心に使用し、その後、人々は最新のマイルストーンを達成するために忙しくなり、それが最後になります。誰もがそれについて聞いています。
組織、分野、開発する製品の種類などによって、いくつかの解決策がありますが、何らかの方法でシステムをセットアップして使用する必要があります。誰かを公式のドキュメンテーション担当者に任命し、手がかりを与えて、彼らが「そうそう、私は来週そのドキュメンテーションを終えるつもりだ...」と言うたびに人々の頭を殴るように言いなさい。それが必要なら。:-)
ツールに関しては… Atlassian のConfluenceをお勧めします。これは優れた wiki であり、エンタープライズ環境で動作するように設計されており、多くの気の利いた機能があり、カスタマイズ可能であり、アトラシアンの他の気の利いたツールのいくつかとうまく統合され、基本的にかなり堅実な製品です。
于 2008-09-19T04:58:52.290 に答える
2
«ソフトウェア ドキュメント» は非常に一般的な用語です。«エンド ユーザー ドキュメント»、«開発者ドキュメント»、«QA ドキュメント»があります。最初のものは通常、資格のあるテックライターによって開発されます。他のものは、wiki やソース コードからのドキュメント コメントなどから動的に形成される場合があります。通常、これらすべてのメンテナンス プロセスは非常に複雑で、各ソフトウェア会社は独自の方法に従っています。しかし、これらすべての方法に必要なポイントが 1 つあります。各コード コミッター、アーキテクト、マネージャー、エンジニアは、他の人にとって役立つ可能性のある情報を適切に整理して保存する必要があります。そして、他の誰かがこのピースの保管を監視し、必要に応じてピースを再配置する必要があります。このすべてのステップにより、開発プロセスに関連するすべてのアクティビティが大幅に改善されます。
于 2008-09-19T04:26:16.893 に答える
1
現在、外部アプリケーション (PHP + PhpDocumenter) とさまざまな内部 wiki によって解析されたインライン ドキュメントを使用しています。せいぜい苦痛な場合もあります (主に 1 人だけが wiki やドキュメントを更新するためです...)
しかし、私はikiwikiを使用して内部文書を作成することを検討しています。ソース管理システム (Git、Subversion、Mercurial、Bazaar、TLA、Monotone を含む) と統合されるため、すべてのドキュメントがプロジェクトを追跡します。Perl で構築され、広範なプラグイン システム (複数のマークアップ言語を含む、デフォルトは Markdown) を備えています。また、ソース管理システムはプラグイン ベースであるため、使用するものがすぐにサポートされない場合は、独自のものを追加できます。Perl以外のプラグインもサポートしているため、必要に応じて好みの言語で。
于 2008-09-19T04:01:51.180 に答える
1
コード ドキュメントとユーザー ドキュメントについて話していると仮定すると、コードのドキュメントを組織外の請負業者やパートナーに配布する必要がない場合は、内部 wiki が最適です。
配布可能なコード ドキュメントが必要な場合は、Javadoc または DOxygen が適しています。
ユーザー ドキュメントを参照している場合は、DITAを参照してください。
于 2008-09-19T03:55:22.833 に答える
1
私は、次の目標を持ってユーザー ドキュメントを作成する方法を試し始めました。
Markdown/Html/Javascript/ファイルベースの相対的にリンクされたドキュメントの移植性 (ローカル ファイル システムで実行するか、Web サーバーで実行できます)、組み込みのスクリーンショットの処理 (対話的にサイズ変更)、および他の誰かが可能性がある場合のオープン ソースクレイジーなもので何かをしたい。
ドキュメント ソースは Markdown で記述され、ブラウザの実行時に Javascript を介して Html にレンダリングされます。
于 2008-09-19T04:17:30.767 に答える
0
私の会社では、さまざまな SharePoint と Wiki を使用しています。要件、プレゼンテーション、契約などの特定のドキュメントの共有ポイント。一方、Wiki は、内部で開発されたライブラリの使用に関するチュートリアルの開発者リポジトリのヘルプ ガイドとして使用されます。
于 2008-09-19T03:52:59.483 に答える
0
ええ、私たちはウィキを使用しています。また、Google ドキュメントも使用しています。Google ドキュメントは、私が試したほとんどの wiki よりも優れていることがわかりました。すべての変更を追跡する必要がなければ、失うものは何もありません。Google ドキュメントは、優れたコラボレーション フレームワークを提供します。
于 2008-09-19T03:55:28.370 に答える