私は、既存の完全に文書化されていないソフトウェア製品の文書化作業を主導する任務を負っています。どのようなリソースが役立つのですか？

私はテクノロジー企業のソフトウェア開発者です。私が取り組んでいる製品の文書化作業を主導する任務を負っています。目標は開発者の内部でドキュメントを作成することであり、プロジェクトはビジネス側に波及し、そこで要件のドキュメントがカバーされます。

このプロジェクトは挑戦的です。具体的には、次のような製品を扱っています。-少なくとも6年間、長い間使用されています。-あちこちにある古くて小さな断片を除いて、ドキュメントの形式はありません。-コード内にコメントがありますが、それらは技術的であり、包括的な技術的な動作を伝えません（技術的な側面でも）。-ドキュメントがほとんどないか、まったくないため、多くの場合、不必要に複雑になっています。

また、このプロジェクトに取り組む時間はあまりありません。

私は正式な文書やライティングの背景、トレーニング、または経験がありません。私は執筆やオフィス内でのコミュニケーション能力を発揮したため、このプロジェクトに割り当てられたのかもしれません。

このプロジェクトの準備と対処に役立つリソースに関するアドバイスや推奨事項を教えてください。マイルストーンを含む計画の設計を思い付き、ベストプラクティス、タスクの委任、テンプレート、バイインなどについて学ぶために、本/ウェブサイト/フォーラム/その他への参照を探しています。

私は特に、既存の、文書化されていないプロジェクトに優れた文書を導入することをターゲットにしたり、特別な言及をしたりするリソースに期待しています。

私は通常、ウィキを使用しており、発見プロセスを実行するときにそこにスパムを送信しています。検索と履歴、およびチーム編集機能を利用できるため、Wiki。正確なツールは、機能する検索を用意し、全員に使用させるほど重要ではありません。最初は非常にラフであると期待しますが、それを最初に取得するのはそれだけなので、人々がそれらの大まかなメモを書くように奨励します。

大いに役立ついくつかのこと：

• エディタを持っています。あなたはおそらく最初はそうですが、予算があればそれを誰かの仕事の一部にしてください。技術的な専門知識よりも言語に長けている人を選んでください。完璧ではなく明確にするために編集します。良いエントリを書くように人々に働きかけたいが、最初はそれらをガイドする必要があります。
• 図を使用しますが、関連するツールが使用され、画像が生成され、ソースファイルがページに添付されるように義務付けます。そうすれば、人々はMS-Paintの代わりに適切なツールを使用して画像を編集できます。元のドキュメントがなく、PNGから抽出されたVisioに組み込まれた非常に優れたダイアグラム以上のものを吸うものはほとんどありません。
• 再配置と編集を奨励します。最初はそれほど良くない場合でも、情報を照合して間違いを修正する人が必要です。これをうまくやるようにメンターに教えてください。
• 毎週のチームミーティングでこれを取り上げてください。先に進む前に最近の編集のリストを入手し、有用なものを追加した人を称賛し、そうでない人、そうでない人に質問してください。

私は始めているMediaWikiの仮想マシンイメージ、それが始めるために非常に迅速かつ簡単なので、人々はどんな初期トラクションを得ることはありません「それはあまりにも難しい」と言って、過去に。

言語/環境がJavaDoc / NDocタイプのツールを使用してそれをサポートしている場合、コメントを追加するときにコメントを抽出することは、低レベルのアプローチとして適しています。しかし、それは高レベルのドキュメントほど有用ではなく、ツールが高レベルのものを追加することをサポートするような種類のツールであっても、それらのツールのみを使用して何もないものから作成することは、不必要に面倒です。

コード自体を文書化し、エンドユーザーの文書化を行わない場合、開発言語がサポートされていれば、Doxygenは優れたツールです。これをコード上で実行すると、すべての関数、クラスなどを一覧表示するWebサイトが作成されます。次に、特別な形式のコードコメントを追加して、グループ化したり、詳細を追加したりできます。これは、コードベースを段階的に文書化する優れた方法です。

コード自体の文書化に関して、Doxygenがニーズに合わない場合、多くの代替ツールが利用可能です。ウィキペディアには、50近くのそのようなツールのリストがあり、それらの機能と言語サポートの詳細が含まれています。

免責事項：私はImagix 4Dというツールの1つに関連付けられています。

これらは、いくつかのレベルで役立つ可能性があるいくつかのアイデアにすぎません。

このドキュメントが最終的にどのような形になるかについて考えましたか？Word文書、DVD、一連のページがアプリケーションを分類するサイト、アプリケーションの詳細をうろたえるブログツールになりますそれは、Share Pointのような既製のドキュメント管理システムを使用しているのでしょうか、それとも他の何かですか？ 結果の取得は、たとえば一連のページであるオンラインブックの例です。

このドキュメントにどのようなバージョン管理と編集プロセスを適用してほしいかは、これに深く入り込む前に熟考する価値のある別の問題です。更新と変更をどのように処理しますか。

フィードバックは、これに関する別の興味深い側面になる可能性があります。作成するものはいくつかの批評である可能性が高く、これらの変更の優先度とスロットルの程度は、最初のバージョンをリリースする前に検討する必要がある別の問題です。

幸運を！

他のすべての種類のソフトウェアの構築と同様に、ドキュメントの構築は本質的に複雑なプロセスです。

ソフトウェア開発者がアジャイル手法を発明したのはそのためです。

ドキュメントはコンパイラのない単なるソフトウェアです。ソフトウェアプロジェクトと同じ方法がドキュメントプロジェクトに適用されます。おそらく同じ理由です。

ソフトウェアを作成するときは、ユースケース（またはユーザーストーリー）から始めます。ドキュメントも同じです。

おおよその予算でユースケースに優先順位を付けます。

あなたはスプリントを持っています。

リリースがあります。

あなたは品質保証、テスト、レビュー、修正、そして再リリースを行います。

これは、ソフトウェアの構築とまったく同じです。

あなたのユーザーは誰ですか？彼らはどんな問題を抱えていますか？文書はどのように彼らの問題を解決しますか？優先する。スプリント。最終的に、あなたは解放します。