cletus Asked: 2009-05-02 22:43:35 +0800 CST2009-05-02 22:43:35 +0800 CST 2009-05-02 22:43:35 +0800 CST 您希望开发人员向您提供什么级别的文档？ 772 标题真的说明了一切。 有时最终会导致开发和 IT 在这类事情上发生争执。当您需要安装、修补、维护、启动、停止和诊断跨一台或多台服务器运行的解决方案时，您期望的文档级别是多少？ documentation 7 个回答 Voted The Archetypal Paul 2009-05-03T00:20:09+08:002009-05-03T00:20:09+08:00 所有这些事情都应该详细记录下来，尽管当操作是操作系统、应用程序服务器、Web 服务器等的标准操作时，您可以假设 IT 操作人员知道如何做到这一点。 安装：记录有关如何安装和配置的所有信息，包括如何判断它是否正常运行。 告诉我们有关架构的信息，尤其是各种解决方案组件之间的通信（例如，端口范围 - RPC 机制通常使用一系列端口 - 我们需要知道范围是什么以及应用程序何时可能会耗尽端口）。 修补：记录任何特定于应用程序的内容 - 修补之前需要关闭的内容，以及修补之后的任何后续操作（可能需要清除或重建的缓存、索引、代理）。 维护：记录正常和异常操作的样子——应该监控哪些队列和其他事情，以及这些的正常范围是多少。 告诉我们如何管理数据——尤其是无限制增长的表和文件（例如日志文件和事务历史）。应该如何清除这些以及删除旧条目的影响是什么？（关于报告等）。 告诉我们如何执行标准的“一切照旧”/生活中的管理行动——例如，这可能是添加或修改用户帐户。 告诉我们可能需要的任何其他常规管理操作（例如，使用了哪些证书以及它们到期时要做什么）。 对于所有更改，告诉我们如何回滚它们（并非所有更改都成功）。并告诉我们您已经测试了回滚计划！ 诊断：记录日志文件格式和位置以及可能出现的每个应用程序错误消息，说明错误消息的含义是什么，以及可能需要更改什么来修复它。永远不要对两个不同的事件使用相同的错误消息。 关闭和启动：如何、按什么顺序、任何特殊程序（例如让服务器在关闭连接之前耗尽连接）。 我强烈反对这样做的最佳方式是将应用程序抛在一边，让 IT 人员找出需要的东西。需要预先考虑操作文档（通常是应用程序的可管理性特性）。 John Saunders 2009-05-08T03:38:13+08:002009-05-08T03:38:13+08:00 一个后续问题是：当（不是如果）开发人员没有提供足够的文档时会发生什么？ 我建议 IT 能够使用开发人员使用的任何缺陷跟踪系统针对软件输入缺陷报告。这样，如果他们没有告诉你，例如，特定文件夹中的文件需要清除，并且只应该保留一周的价值，你可能会输入一个缺陷，说“应用程序用日志文件填充磁盘”，并建议他们与 IT 部门合作，制定用于清除该文件夹的文档化技术。 Martin M. 2009-06-16T08:34:27+08:002009-06-16T08:34:27+08:00 我对文档的要求列表是（不按任何特定顺序）： （文档：） 所有命令行开关 所有退出状态和返回值 日志消息（与其说是内容，不如说是解释字段，如果它是不可配置的） 配置语法 在配置文件中切换 内存使用情况 它是螺纹的还是分叉的 服务器对什么信号做出反应 是否有任何信号不会重新启动服务器但使其重新读取配置 它的行为如何？（它是否等待现有线程/进程完成旧配置。它会杀死它们，...） 不干净的关机会发生什么（特别是如果它是某种持久性服务/服务器） 它是通过系统提供的调用记录还是使用自己编写的内容进行记录（对于apache和访问日志来说很糟糕——我显然更喜欢用于记录的板载工具） 如果它是网络服务，则准备好 IPv4 和 IPv6 主干文档和特定版本的文档 没有什么比配置几个小时更糟糕的了，只是为了发现它会被忽略，因为配置选项仅在主干中可用 哪个配置选项在哪个版本中有效（自：v1.0 可用，自：v1.2 或类似版本后弃用） 像这样的文档是良好文档的示例： http://httpd.apache.org/docs/2.2/ http://www.postgresql.org/docs/8.3/static/index.html 我认为这样的文档充满了失败： http://tomcat.apache.org/tomcat-6.0-doc/index.html FreeBSD 手册也是文档和 OpenBSD 方法的一个很好的例子。他们踢出没有正确记录的东西。 编辑：这个列表绝不是完整的，它只是我立即想到的基本内容。此外，文档应该易于阅读，而不仅仅是读起来像某人吐了的东西。 Jim C 2009-05-28T12:51:56+08:002009-05-28T12:51:56+08:00 简而言之，我期望我指定并签订合同的文档。 太多次，这个关键细节被遗漏在协议之外。最终用户当然希望它并免费获得它。优秀的开发人员会在流程的早期纠正这种疏忽，并设定包括价格和时间要求在内的期望。 Spoike 2009-05-02T23:06:06+08:002009-05-02T23:06:06+08:00 我相信 IT 需要与开发人员沟通需要什么样的文档。做到这一点的最佳方法是，如果开发人员提供解决方案的预发布版本（或迭代版本）供 IT 使用和测试，以便 IT 可以根据需要做出响应。 user1804 2009-05-05T15:28:31+08:002009-05-05T15:28:31+08:00 使用应用程序创建足够的发行说明将是一个好的开始。如果发布时当前行为发生变化，QA 的任何注释关于依赖项或启动/停止行为的变化、依赖服务器或数据库的负载变化等。 Netais LLC 2009-05-28T10:10:42+08:002009-05-28T10:10:42+08:00 @Spoike（我还不能评论答案..） IT 实施者（角色因公司类型和规模而异）必须始终如一地工作以实现以下目标： 安装/周转最低要求- 换句话说，IT 不能被动地期望开发人员在安装/周转时“知道”需要哪些信息。我发现 IT 部门对于应用程序的正确文档构成通常存在相当大的混淆/分歧。开发人员了解需求（我们希望如此），IT 必须进行核心讨论，以找出（至少）需要什么。 安装/周转过程- 在企业设置中，您可能称之为变更控制或治理，但它本质上是一个标准审查周期，其中 IT 与 Dev PRIOR 顶部安装坐下来了解产品及其需求的简报。 安装应用程序与首次亮相戏剧作品没有什么不同。在大幕拉开之前，导演（首席开发人员）与舞台制作团队（IT 实施人员）反复会面，以确保开幕之夜（公共安装）的一切都“正常”。 你无法改变 Dev 角色（你为什么要这样做？），但你可以指出你的共同目标，即为所有用户快速运行的出色应用程序。您的共识 IT 文档要求只是确保这一点所需的事情之一。
所有这些事情都应该详细记录下来，尽管当操作是操作系统、应用程序服务器、Web 服务器等的标准操作时，您可以假设 IT 操作人员知道如何做到这一点。
安装：记录有关如何安装和配置的所有信息，包括如何判断它是否正常运行。
告诉我们有关架构的信息，尤其是各种解决方案组件之间的通信（例如，端口范围 - RPC 机制通常使用一系列端口 - 我们需要知道范围是什么以及应用程序何时可能会耗尽端口）。
修补：记录任何特定于应用程序的内容 - 修补之前需要关闭的内容，以及修补之后的任何后续操作（可能需要清除或重建的缓存、索引、代理）。
维护：记录正常和异常操作的样子——应该监控哪些队列和其他事情，以及这些的正常范围是多少。
告诉我们如何管理数据——尤其是无限制增长的表和文件（例如日志文件和事务历史）。应该如何清除这些以及删除旧条目的影响是什么？（关于报告等）。
告诉我们如何执行标准的“一切照旧”/生活中的管理行动——例如，这可能是添加或修改用户帐户。
告诉我们可能需要的任何其他常规管理操作（例如，使用了哪些证书以及它们到期时要做什么）。
对于所有更改，告诉我们如何回滚它们（并非所有更改都成功）。并告诉我们您已经测试了回滚计划！
诊断：记录日志文件格式和位置以及可能出现的每个应用程序错误消息，说明错误消息的含义是什么，以及可能需要更改什么来修复它。永远不要对两个不同的事件使用相同的错误消息。
关闭和启动：如何、按什么顺序、任何特殊程序（例如让服务器在关闭连接之前耗尽连接）。
我强烈反对这样做的最佳方式是将应用程序抛在一边，让 IT 人员找出需要的东西。需要预先考虑操作文档（通常是应用程序的可管理性特性）。
一个后续问题是：当（不是如果）开发人员没有提供足够的文档时会发生什么？
我建议 IT 能够使用开发人员使用的任何缺陷跟踪系统针对软件输入缺陷报告。这样，如果他们没有告诉你，例如，特定文件夹中的文件需要清除，并且只应该保留一周的价值，你可能会输入一个缺陷，说“应用程序用日志文件填充磁盘”，并建议他们与 IT 部门合作，制定用于清除该文件夹的文档化技术。
我对文档的要求列表是（不按任何特定顺序）：
（文档：）
像这样的文档是良好文档的示例：
我认为这样的文档充满了失败：
FreeBSD 手册也是文档和 OpenBSD 方法的一个很好的例子。他们踢出没有正确记录的东西。
编辑：这个列表绝不是完整的，它只是我立即想到的基本内容。此外，文档应该易于阅读，而不仅仅是读起来像某人吐了的东西。
简而言之，我期望我指定并签订合同的文档。
太多次，这个关键细节被遗漏在协议之外。最终用户当然希望它并免费获得它。优秀的开发人员会在流程的早期纠正这种疏忽，并设定包括价格和时间要求在内的期望。
我相信 IT 需要与开发人员沟通需要什么样的文档。做到这一点的最佳方法是，如果开发人员提供解决方案的预发布版本（或迭代版本）供 IT 使用和测试，以便 IT 可以根据需要做出响应。
使用应用程序创建足够的发行说明将是一个好的开始。如果发布时当前行为发生变化，QA 的任何注释关于依赖项或启动/停止行为的变化、依赖服务器或数据库的负载变化等。
@Spoike（我还不能评论答案..）
IT 实施者（角色因公司类型和规模而异）必须始终如一地工作以实现以下目标：
安装/周转最低要求- 换句话说，IT 不能被动地期望开发人员在安装/周转时“知道”需要哪些信息。我发现 IT 部门对于应用程序的正确文档构成通常存在相当大的混淆/分歧。开发人员了解需求（我们希望如此），IT 必须进行核心讨论，以找出（至少）需要什么。
安装/周转过程- 在企业设置中，您可能称之为变更控制或治理，但它本质上是一个标准审查周期，其中 IT 与 Dev PRIOR 顶部安装坐下来了解产品及其需求的简报。
安装应用程序与首次亮相戏剧作品没有什么不同。在大幕拉开之前，导演（首席开发人员）与舞台制作团队（IT 实施人员）反复会面，以确保开幕之夜（公共安装）的一切都“正常”。
你无法改变 Dev 角色（你为什么要这样做？），但你可以指出你的共同目标，即为所有用户快速运行的出色应用程序。您的共识 IT 文档要求只是确保这一点所需的事情之一。