私は、既存の完全に文書化されていないソフトウェア製品の文書化の取り組みを主導する任務を負っています-私を助けるためにどのようなリソースがありますか？
私はテクノロジー企業のソフトウェア開発者です。私が取り組んでいる製品の文書化作業を主導する任務を負っています。目標は、開発者の内部でドキュメントを作成することであり、プロジェクトはビジネス側に波及し、要件のドキュメントがカバーされます。
このプロジェクトは挑戦的です。具体的には、次のような製品を扱っています。-少なくとも6年間、長い間使用されています。 -あちこちにある古くて小さな断片を除いて、ドキュメントの形式はありません。 -コード内にコメントがありますが、それらは技術的であり、包括的な技術的な動作を伝えません（技術的な側面でも）。 -ドキュメントがほとんどないか、まったくないため、多くの場合、不必要に複雑になっています。
また、このプロジェクトに取り組む時間はあまりありません。
私は正式なドキュメントやライティングの背景、トレーニング、または経験がありません。私は執筆やオフィスでのコミュニケーション能力を発揮しました。そのため、このプロジェクトに割り当てられました。
このプロジェクトの準備と対処に役立つリソースに関するアドバイスや推奨事項を教えてください。マイルストーンを含む計画の設計を思い付き、ベストプラクティス、タスクの委任、テンプレート、バイインなどについて学ぶために、本/ウェブサイト/フォーラム/その他への参照を探しています。
私は特にリソースをターゲットにすることを望んでいるか、または良いドキュメントを紹介することについて特別な言及をしています ドキュメント化されていない既存のプロジェクト。
私は通常wikiを使用しており、発見プロセスを実行するときにそこにスパムを送信します。検索と履歴、およびチーム編集機能を利用できるWiki。正確なツールは、機能する検索を用意し、みんなに使ってもらうほど重要ではありません。最初は非常にラフであると期待しますが、それを最初に取得するのはそれだけなので、人々がそれらのラフなメモを作成することをお勧めします。
大いに役立ついくつかのこと：
- エディタを持っています。あなたはおそらく最初はそうですが、予算があればそれを誰かの仕事の一部にしてください。技術的な知識よりも、言語に長けている人を選んでください。完璧ではなく明確にするために編集します。良いエントリを書くように人々に働きかけたいが、最初はそれらをガイドする必要があります。
- 図を使用しますが、関連するツールが使用され、画像が生成され、ソースファイルがページに添付されるように義務付けます。そうすれば、人々はMS-Paintの代わりに適切なツールを使用して画像を編集できます。元のドキュメントがなく、PNGだけが抽出されたVisioに組み込まれている本当に優れた図よりも、それを吸い込むものはほとんどありません。
- 再配置と編集を奨励します。最初はそれほど良くない場合でも、情報を照合して間違いを修正する人が必要です。これをうまくやるようにメンターにメンターしてください。
- 毎週のチームミーティングでこれを取り上げてください。先に進む前に最近の編集のリストを入手し、有用なものを追加した人を称賛し、そうでない人、そうでない人に理由を尋ねてください。
私は MediaWiki仮想マシンイメージ から始めましたが、それは非常に速く簡単に始めることができるため、「難しすぎる」と言っている人は最初の牽引力を得ることはありません。
言語/環境がJavaDoc/NDocタイプのツールを使用してそれをサポートしている場合、コメントを追加するときにコメントを抽出することは、低レベルのアプローチとして適しています。しかし、それは高レベルのドキュメントほど有用ではなく、ツールが高レベルのものを追加することをサポートしているにもかかわらず、それらのツールのみを使用して何もないものからそれを作成することは、不必要に面倒です。
コード自体を文書化し、エンドユーザーの文書化を行わない場合、開発言語がサポートされていれば、Doxygenは優れたツールです。コード上で実行すると、すべての関数、クラスなどを一覧表示するWebサイトが作成されます。次に、特別な形式のコードコメントを追加して、グループ化し、詳細を追加できます。これは、コードベースを段階的に文書化する優れた方法です。
これらは、いくつかのレベルで役立つ可能性があるいくつかのアイデアにすぎません。
このドキュメントが最終的にどのような形式になるかについて考えましたか？Word文書、DVD、一連のページがアプリケーションを分類するサイト、アプリケーションの詳細をうろたえるブログツールになりますそれは、Share Pointのような既成のドキュメント管理システム、または何か他のものを使用していますか？ 結果の取得 は、たとえば一連のページであるオンラインブックの例です。
このドキュメントにどのようなバージョン管理と編集プロセスを適用してほしいかは、これに深く入り込む前に熟考する価値のある別の問題です。更新と変更をどのように処理しますか？.
フィードバックは、これについて別の興味深い側面になる可能性があります。作成するものはいくつかの批評である可能性が高く、これらの変更の優先度と抑制の程度は、最初のバージョンをリリースする前に検討する必要がある別の問題です。
幸運を！
他のすべての種類のソフトウェアの構築と同様に、ドキュメントの構築は本質的に複雑なプロセスです。
ソフトウェア開発者がアジャイル手法を発明したのはそのためです。
ドキュメンテーションはコンパイラのない単なるソフトウェアです。ソフトウェアプロジェクトと同じ方法がドキュメントプロジェクトに適用されます。おそらく同じ理由です。
ソフトウェアを作成するときは、ユースケース（またはユーザーストーリー）から始めます。ドキュメントも同じです。
おおよその予算でユースケースに優先順位を付けます。
あなたはスプリントを持っています。
リリースがあります。
あなたは品質保証、テスト、レビュー、修正、そして再リリースを行います。
それは正確にビルドソフトウェアのようなものです。
あなたのユーザーは誰ですか？彼らはどんな問題を抱えていますか？文書はどのように彼らの問題を解決しますか？優先する。スプリント。最終的に、あなたは解放します。