如何为新开发人员编写网站/软件的技术文档？

Question

我想为开发人员制作现有网站的技术文档，以便新开发人员可以继续使用它。在现有的代码中，很少（或根本不）代码注释或文档字符串可用（我知道不好的做法）。是的，我看过一些与这些相关的帖子。但那些细节并不那么详细。以下是我的所有问题：

• 要包含什么？
• 如何组织？我的意思是，你可以提出一些层次结构，以便新开发人员可以轻松进入该轨道吗？
• 什么是最佳实践？
• 你能展示一些样品吗？
• 它如何变得简单？一些ppl建议维基工具，但我对此一无所知，它会有用吗？你能用一些快速入门教程来提示任何工具吗？

我从来没有打过一个。所以我很欣赏任何答案。提前致谢。 （链接将是有益的，但请给它的快速和清晰的总结）

Answer 1

快速和清晰的：

---

认为它像任何纸张。

什么是目标应用（网站）的？ [为什么？]
它是如何实现这一目标的？
出现了什么问题？
可能会出现什么问题？
什么可以扩展？ [为什么？]
扩展可能导致什么问题？ [为什么？]
应继续遵循什么命名/格式约定？

• 大纲格式是伟大的。

Answer 2

除了诺娜的建议，我也可以说，它打破代码并解释代码的任何约定和意图，以便有喜欢的事情ID值，CSS类开发商之间的一致性是非常重要的，而JavaScript函数名称。如你确定的那样具体，以防止新员工重新开始工作。

Answer 3

如果你正在寻找一个快速的方式，通过你的代码来获得，尝试.NET Reflector。它为您提供了所有类，方法，属性等的广泛概述，以便您可以编写所需的所有技术文档，而无需实际浏览文件。浏览起来非常简单，它甚至会显示代码本身。

Answer 4

你有没有想过代表的是有一些UML符号？这就是UML的用途！如果新开发者很好，那么他们应该能够理解它。