您希望开发人员提供什么级别的文档?


8

标题确实说明了一切。

有时最终可能会导致开发和IT在这类事情上处于僵局。当您期望安装,修补,维护,启动,停止和诊断在一个或多个服务器上运行的解决方案时,您期望什么级别的文档?


Answers:


9

所有这些内容都应详细记录在案,尽管当该操作是操作系统,应用程序服务器,Web服务器等的标准配置时,您可能可以假设IT操作人员会知道该怎么做。

安装:记录有关如何安装和配置的所有信息,包括如何判断其是否正常运行。

告诉我们有关体系结构的信息,特别是有关各种解决方案组件之间的通信的信息(例如,端口范围-RPC机制经常使用一定范围的端口-我们需要知道范围是什么,以及应用程序何时可能会用尽端口)。

修补程序:记录特定于应用程序的所有内容- 修补程序之前需要关闭的内容,以及修补程序之后应进行的任何后续操作(可能需要清除或重建的缓存,索引,代理)。

维护:记录正常和异常操作的状态-应监视哪些队列和其他内容以及这些内容的正常范围。

告诉我们如何管理数据-特别是无限制增长的表和文件(例如日志文件和事务历史记录)。这些应该如何清除?删除旧条目会有什么影响?(关于报告等)。

告诉我们如何执行标准的“一切照常” /生活管理操作-例如,这可能是添加或修改用户帐户。

告诉我们其他可能需要采取的其他常规管理措施(例如,使用了哪些证书以及证书到期后该怎么做)。

对于所有更改,请告诉我们如何回滚它们(并非所有更改都成功)。并告诉我们您已经测试了回滚计划!

诊断:记录日志文件的格式和位置,以及可能出现的每个应用程序错误消息,指出错误消息的含义是错误的,以及可能需要更改以修复该错误消息。切勿对两个不同的事件使用相同的错误消息。

击落并启动:如何,以什么顺序执行任何特殊程序(例如,让服务器在关闭连接之前先排空连接)。

我强烈不同意这样做的最佳方法是将应用程序扔到栅栏上,让IT人员确定需要什么。需要事先考虑操作文档(通常是应用程序的可管理性功能)。


1
哇,这个层面的知识有关部署,没关系的文件系统之前,将是惊人的。这不是为什么有些公司在开发人员中聘用SRE而不是依靠开发人员这样思考吗?
考夫兰兹

的确,大多数开发人员都不会考虑这些事情(我既是软件开发人员,还是后来在基础架构管理公司中担任架构师,而后者令人大开眼界...)。我认为开发人员应该了解这些主题,但是如果他们不了解,那么专家的共同努力是前进的方向。这实际上是关于软件重要问题的更广泛问题的一部分-价值是正在执行和可用的软件-提供服务,而不仅仅是功能完善。我可能需要问另一个问题,以便我能更深入地回答:)
原型保罗

2

接下来的问题是:当(如果不是)开发人员没有提供足够的文档时会发生什么?

我建议IT人员能够使用开发人员使用的任何缺陷跟踪系统,针对软件输入缺陷报告。这样,例如,如果他们没有告诉您需要清除特定文件夹中的文件,并且只保留一周的时间,则您可能会输入以下缺陷:“应用程序将日志文件填充到磁盘中”,并建议他们与IT一起使用清除该文件夹的已记录技术。


是的,去过那里。开发人员花了四个星期的时间告诉我们如何清除不断增长的三张桌子。提前考虑一下。但是,我非常同意您的观点,即可管理性问题是软件中的缺陷...
原型保罗,

我通常拒绝部署未记录的服务器(如在守护程序中)。如果我真的需要武力部署它们(管理要求),那么我明确指出要弄清楚所有这些东西将花费多少费用
Martin M.

2

我的文档要求清单为(不按任何特定顺序):

(有关文档:)

  • 所有命令行开关
  • 所有退出状态和返回值
  • 日志消息(不是很多内容,而是在无法配置的情况下解释字段)
  • 配置语法
  • 切换配置文件
  • 内存使用情况
  • 它是螺纹的还是分叉的
  • 服务器反应的信号是什么
    • 是否有任何信号不会重新启动服务器,而是使其重新读取配置
    • 它的表现如何?(它是否等待现有线程/进程完成旧配置。是否杀死它们,...)
  • 不正常关机时会发生什么(特别是如果它是某种持久性服务/服务器)
  • 它是通过系统提供的呼叫来记录日志,还是使用自己编写的东西记录日志(为apache和访问日志而烦恼 -我显然更喜欢使用板载工具进行日志记录)
  • 如果是网络服务,则支持IPv4和IPv6
  • 中继上的文档和特定版本上的文档
    • 没有什么事情比配置几个小时发现它会被忽略,因为config选项仅在主干中可用
  • 哪个配置选项在哪个版本中有效(自v1.0起可用,自v1.2以来不推荐使用)

像这样的文档是良好文档的示例:

我认为像这样的文档充满了失败:

FreeBSD手册也是文档和OpenBSD方法的一个很好的例子。他们将没有适当记录的东西赶出去。

编辑:此列表绝不是完整的,它只是我立即想到的基本内容。同样,文档应该易于阅读,而不仅仅是像有人吐出来的东西


1

简而言之,我希望我能指定并签订合同。

这个关键细节太多次被排除在协议之外。最终用户当然会期望并免费。优秀的开发人员将尽早纠正这种疏忽,并设定期望,包括价格和时间要求。


0

我相信IT部门需要与开发人员沟通,需要什么样的文档。最好的方法是开发为IT提供解决方案的预发行版本(或迭代发行版)以供IT玩耍和测试,以便IT可以对所需信息做出响应。


0

使用应用程序创建适当的发行说明将是一个好的开始。如果该发行版中的当前行为发生了变化,则QA中有关依赖关系或启动/停止行为的变化,对从属服务器或数据库的负载的变化等的任何注释。


0

@Spoike(我无法评论答案..)

IT实施者(角色将因公司类型和规模而异)必须一致地工作以实现以下目标:

  • 安装/周转最低要求 -换句话说,IT不能是被动的,希望开发人员在安装/周转时“知道”需要什么信息。我发现,对于什么构成应用程序的正确文档,IT领域经常存在很大的混乱/分歧。开发人员了解需求(我们希望如此),并且IT部门必须谨慎地寻找至少需要的内容。

  • 安装/周转过程 -在企业设置中,您可以称其为“变更控制或治理”,但这本质上是一个标准的审查周期,其中IT部门与Dev PRIOR顶级安装人员坐下来,以简要了解产品及其需求。

安装应用程序无异于首次上演戏剧作品。在帷幕拉开之前,导演(首席开发人员)与舞台制作团队(IT实施者)反复会面,以确保开幕之夜(公共安装)一切都“如此”。

您无法更改开发人员角色(为什么要这么做?),但是您可以指出您的共同目标,即为所有用户快速运行的出色应用程序。您对IT文档的共识要求只是确保做到这一点的必要条件之一。

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.