Api 缺乏参考级文档？
我的工作倾向于使用其他地方的工具和库，而不是提供这些东西供外部使用。但对于我们内部所做的工作，“文档”意味着提供信息，简洁地列举供其他人使用的功能。根据习惯，我们倾向于生成看起来像UNIX的人页，但我不认为我们认为最终的格式。 然而，当涉及到我们使用的（主要是.NET）库和工具时，这一级别的信息似乎非常稀少，甚至对于IDE中的“F1”类型的帮助也是如此 我们在评估准确、简洁的API（和类似的）参考资料方面是否与众不同？其他人容易发现吗？或者你觉得教程、演练和视频更有价值吗 我认为这将是第一个也是最容易生产的材料，因为这是一个受控开发和发布过程的强制性要求Api 缺乏参考级文档？,api,documentation,reference,Api,Documentation,Reference,我的工作倾向于使用其他地方的工具和库，而不是提供这些东西供外部使用。但对于我们内部所做的工作，“文档”意味着提供信息，简洁地列举供其他人使用的功能。根据习惯，我们倾向于生成看起来像UNIX的人页，但我不认为我们认为最终的格式。 然而，当涉及到我们使用的（主要是.NET）库和工具时，这一级别的信息似乎非常稀少，甚至对于IDE中的“F1”类型的帮助也是如此 我们在评估准确、简洁的API（和类似的）参考资料方面是否与众不同？其他人容易发现吗？或者你觉得教程、演练和视频更有价值吗 我认为这将是第一个也是
目前，这种恶化的一个很好的例子是关于ASP.NET MVC，但我并不想特别指出它是异常的，只是典型的。忘了MVC吧，我希望MS能够为常规的.NET库提供像样的文档。在我记忆中，微软的文档几乎不可用；几乎是废话 我偶尔会无意中撞上F1，然后翻阅MSDN文档。和往常一样，几分钟后我意识到谷歌更快了 作为一个示例，只需看看查找datetime字符串格式字符需要多长时间
我认为大多数第三方供应商都有这种情况 忘了MVC吧，我希望MS能够为常规的.Net库提供像样的文档。在我记忆中，微软的文档几乎不可用；几乎是废话 我偶尔会无意中撞上F1，然后翻阅MSDN文档。和往常一样，几分钟后我意识到谷歌更快了 作为一个示例，只需看看查找datetime字符串格式字符需要多长时间
我认为大多数第三方供应商都有这种情况 不同类型的文档适用于不同的用途
- 当您需要广泛了解如何使用某项技术时，视频可以为您提供10000英尺的功能视图。但这些很少显示可读的API使用示例
- 当您需要使用该技术组合一个基本项目时，一个循序渐进的教程就很好了。但这些并没有向你展示异国情调的案例或最佳实践；它们只显示了使用该技术的一种场景
- 当您需要学习使用该技术设计解决方案的最佳实践，或者学习与其他技术集成的方法时，面向任务的文档是最佳选择
- 如果您对该技术非常熟悉，但只需要方法签名等的参考，那么API文档是合适的。这些可以集成到IDE中
始终缺乏有效的文档。ASP.NETMVC可能是一个例子，但在Java世界中它并没有好多少。是的，Javadoc参考资料在线提供，但许多条目都是琐碎的或占位符文本。API参考文档通常不足以解释如何在应用程序设计的上下文中最好地使用每个给定的类和方法。不同类型的文档对于不同的用法是合适的（并且是必要的）
- 当您需要广泛了解如何使用某项技术时，视频可以为您提供10000英尺的功能视图。但这些很少显示可读的API使用示例
- 当您需要使用该技术组合一个基本项目时，一个循序渐进的教程就很好了。但这些并没有向你展示异国情调的案例或最佳实践；它们只显示了使用该技术的一种场景
- 当您需要学习使用该技术设计解决方案的最佳实践，或者学习与其他技术集成的方法时，面向任务的文档是最佳选择
- 如果您对该技术非常熟悉，但只需要方法签名等的参考，那么API文档是合适的。这些可以集成到IDE中