開発チームのサポート/メンテナンスのドキュメント

Question

私は大規模な電子商取引会社の開発部門（約40名の開発者）に勤めています。私たちは急速に成長しましたが、私たちは仕事を文書化する分野では進化していません。開発とテストでは、アジャイル/スクラムのような方法論で作業しますが、ドキュメントは無視されているようです。

私たちは、プロジェクトに参加していない開発者を支援するための文書を作成する必要があります。また、追加の構成設定や発生する可能性のある既知の問題の修正について説明するため、サポート部門のより高度な情報を作成する必要があります。

現在、これは古いSharePoint/TFSサイトに基づいて、ひどく入れられたwikiに入れています。

ドキュメントの標準を改善するための理想的なリンクやアドバイスはありますか？他の企業では何ができますか？

アジャイルプロセスの一環としてドキュメントをどのように開発できますか？

Answer 1

すべてのメソッドの上にDoxygenコメントブロックを使用し、毎晩Doxygenを実行するので、ドキュメントは毎晩作成され、プロジェクトイントラネットページで出力にアクセスできます。また、コードレビュープロセスの一環としてsourcemonitorを使用します。ソースコードの行に対するコメント行の比率を満たす必要があります。人々は時々これを回避するために不正行為をするが、コードは手動でもレビューされるので、悪用される。

Answer 2

完全bookは、このトピックの内容を捧げました。

一般的に、「あまりにも多い」と「全くない」との間の適切なトレードオフを見つけることは非常に困難です。

一般的に私はチームコミュニケーションにリソースを投資するほうが、誰も読んでいないような、古いものよりもはるかに古いテキストよりも助長されていることがわかりました。私は、新しい開発者は、コード、プロセス、チームの文化を十分に理解しているメンターを取得することをお勧めします。メンタリングの際には、ドキュメントが不足していて、より完全なものにすることさえできます。古いコンテンツを削除することも非常に重要です。間違ったドキュメントは非常に混乱し、どれも悪いほどです。

「レシピ」のようなアクションは、文書化するのに適しています。 checklists、開発セットアップ、FAQまたはトラブルシューティングのリスト

EDIT：固定リンク

Answer 3

私はあなたを助けるかもしれないadd-in for Visual Studio（2010年、2008年、2005年）を書きました。任意のタイプのコード要素（C＃、C++、C++/CLI、C、Java、およびVisual Basic）のドキュメント（Documentation XML、DoxygenまたはJavaDoc）を自動生成および更新することができます。それは、あなたのコード（ネーミング、スローされた例外、既に他のメソッドやベースクラスに存在する他のドキュメント）からできるだけ多くの情報を集めてインテリジェントに集計し、大量のドキュメンテーションを生成します。興味深く重大な文書（「自己文書化」コードから神ができない「なぜ」と「どのように」の説明）。また、ドキュメントを更新してコードへのチャンクとの同期を維持し、コードの保守負担を最小限に抑えるためにフォーマットを整理します（ワードラッピングなどで）。これは素晴らしい時間を節約するもので、ずっと面倒なビジネスを文書化することができます。これは、実際にコードを文書化するためのいくつかのタイプの開発者を得ることができる唯一の方法です。アドバイスの

Answer 4

あなたがスクラムを使用する場合は2つのビット：

• あなたがそれを行う一度/コード化されたものを文書化すると、完了のあなたの定義に変更を追加し、以降その瞬間から、それをあなたが行う場合、すべてを施行開始となります文書化されているか、または不完全とみなされます。これにより、問題が表示され、問題を修正するのに役立ちます。
• あなたは過去の仕事を文書化するために明示的に作業する必要があるので、バックログに適切なストーリーを追加してプロダクトオーナーを説得​​する必要があります。