新しい開発者向けのWebサイト/ソフトウェアの技術文書を書くには？

Question

私は、開発者のための既存のWebサイトの技術文書を作成して、新しい開発者が引き続きそのWebサイトで作業できるようにしたいと考えています。既存のコードでは、コード内のコメントやドキュメント文字列がほとんどない（またはまったくない）（悪い習慣、私が知っている）。ええ、私はこれらに関連するいくつかの記事を見てきました。しかし、それらは詳細ではなかった。ここにすべての質問があります：

• どのように整理するのですか？つまり、新しい開発者が簡単に軌道に乗ることができるように階層を提案できますか？
• ベストプラクティスは何ですか？
• いくつかのサンプルを表示できますか？
• どうすれば簡単にできますか？いくつかのpplはwikiツールを示唆していますが、私はそれについて何も知らないので、役に立つでしょうか？いくつかの簡単なチュートリアルのツールを提案できますか？

私は決して1つを作っていません。だから私はどんな種類の答えにも感謝します。前もって感謝します。 （リンクが役に立つことが、それを迅速かつ明快な要約をお願いします）

Answer 1

迅速かつ明快：

---

は、任意の紙と同じように考えてください。

アプリ（ウェブサイト）のゴールとは何ですか？ [なぜ？]
この目標はどのように達成されますか？
どのような問題が発生しましたか？
どのような問題が発生する可能性がありますか？
拡張できるものは何ですか？ [なぜ？]
拡張が原因で問題が発生する可能性はありますか？ [なぜ？]
どんな名前付け/書式設定の規則に従わなければなりませんか？

• アウトラインフォーマットは素晴らしいです。

Answer 2

ノナの提案に加えて、コードを分解してコードの慣習や意図を説明して、ID値、CSSクラス、およびコードなどの開発者間で一貫性があることを説明することも重要ですJavaScript関数名。新しい人がチームに働きかけないようにするために必要なことを特定した上で具体的にしてください。

Answer 3

コードを簡単に検索するには、.NET Reflectorをお試しください。すべてのクラス、メソッド、プロパティなどの概要を提供し、必要なすべての技術文書を実際にファイルに書き込まずに記述することができます。ブラウズするのが簡単で、コード自体も表示されます。

Answer 4

UML表記で何が表示されているか考えましたか？それがUMLです新しい開発者が良いのであれば、それを理解できるはずです。