Questions tagged «documentation»

软件文档是计算机软件随附的书面文本。它说明了该软件如何运行,如何安装,如何使用它以及其他寻求帮助的资源。


7
设计文件中应包含对给定设计的利弊的讨论,还是应集中于事实和理由?
我目前正在更新设计文档,以使其对未来的开发人员来说是正确的和最新的。 当前,该文档仅关注事实,介绍设计的方式。提出的任何决定都没有理由。我认为,掌握基本原理很重要,这样开发人员才能知道事情为什么如此,因为这很可能会影响未来的决策。对于我来说,不可能为所有设计决策(尤其是在我开始从事该项目之前所做的决策)添加依据,但是我正在本部门尽我所能。 但是,考虑到项目的要求,某些设计决策是非常糟糕的决策。不过,也有一些不错的。 我最初的想法是,我应该讨论设计问题以及针对这些问题的潜在解决方案或变通办法,以引起未来维护者的注意,但是我不确定设计文档是否适合进行此类讨论和提供信息。我不希望其他人在该系统上工作并更新文档时使设计“批判”猛增到“撕毁该设计的新特性”,因为这显然是不合适的。 我的经理会支持任何一个决定,所以这取决于我。无论采用哪种方法,生成的文档都将进行正式版本控制,并通常在执行开发任务之前将其提供给系统上的开发人员。期望新的开发人员在开始开发工作之前先熟悉与给定软件系统相关的文档。 问题: 设计文件应遵循原始事实(“这就是设计”)和基本原理(“这就是设计的原因”)还是应该用于指出设计中可能存在问题的无缺陷问题未来的开发商? 如果不应该使用设计文档来捕获这些信息,那么应该通过讨论设计原理,权衡和已知问题(不是缺陷,因为可以跟踪缺陷)的讨论,应该捕获哪种类型的文档,以及应该捕获什么其他类型的文档?使用其他工具)?

5
如何记录已经开发的项目?
我想知道哪些选项可用于记录已开发的项目,因为从事该项目的开发人员甚至没有编写任何页面的文档。 该项目没有其他细节,只有许多页面的脚本具有过去两年来从事该项目的开发人员编写和修改的功能。我所拥有的只是数据库架构和项目文件。我想知道是否有任何方法可以组织这个项目并将其记录下来,从而对将来将从事此项目的开发人员有所帮助。 该项目是使用PHP和MySQL开发的。这些函数的注释很差,所以用doxygen运行时无法获得良好的结果。

1
如何表示我的MongoDB数据库的架构图?
我有一个MongoDB数据库,我想正确地记录其架构设计。我知道MongoDB是一个NoSQL数据库,本质上是无模式的,但是我确实通过我的应用程序强制执行一个模式,并且我希望用一种比打印findOne()结果更好的方式表示它。 我看到许多人使用ER或UML,但是我觉得将NoSQL数据库表示为关系数据库是不正确的,至少看起来很奇怪。 使用UML的示例:MongoDB:如何在论文中表示模式图? 我认为人们会使用不同的模型。我进行了搜索,到目前为止,所看到的是MongoVUE,它提供了一个不错的Tree视图来理解该模式,但是它不便于打印。 NoSQL世界还缺少我一些东西吗?还是应该休息并坚持使用传统的UML?

3
如何阅读RFC和类似文档?[关闭]
已关闭。这个问题需要细节或说明。它当前不接受答案。 想改善这个问题吗?添加细节并通过编辑此帖子来澄清问题。 4年前关闭。 RFC: 征求意见书(RFC)是Internet工程任务组(IETF)发布的备忘录,描述了适用于Internet和Internet连接系统的工作方法,行为,研究或创新。 在结束这个介绍给REST视频,RFC2616和RFC3986被提及作为进一步阅读。观看视频后,我用谷歌搜索了这些文档,正如标题所示,我不确定如何使用它们。我会完整阅读它们并做笔记吗?还是在我不懂或有问题时更多地使用它们作为参考?

5
让开发人员执行项目管理的软件经理
我是一家嵌入式系统公司的软件开发人员。我们有一个项目经理,他负责整个项目进度表(包括电气,质量,软件和制造),因此他的软件进度表非常简短。 我们还有一个软件经理,我的老板。他让我编写和维护软件进度表,设计文档(高低级设计),SRS,变更管理,验证计划和报告,发布管理,审阅,当然还有软件。 我们整个软件团队只有一名测试工程师(十名成员),并且在任何给定时间,都有几个项目正在进行。 我花了80%的时间制作这些文档。我的老板来自流程方面,并且认为我们需要更好的文档来改进软件: 他认为设计是最重要的,编码是“只是将设计写下来”,时间不要太长,并且“所有代码都应在硬件准备好之前编写”。 即使我们告诉他与分布式模型的协作更轻松,也不了解中央版本控制和分布式版本控制之间的区别。 不懂代码,想了解每个错误及其建议的解决方案。 认为验证应由开发人员完成,测试人员应进行验证。事实是,我们的验证仅检查实现是否正确(我们不编写单元测试,在计划中从未考虑过),而验证是黑盒测试,因此缺少单元测试。 我真的很困惑 我负责维护所有这些文件吗?本质上,这让我感到自己正在执行软件项目管理。我可以接受技术文档,但我相信开发人员不应该进行计划/计划。 我不太喜欢创建文档,我想解决问题并编写代码。以我的经验,创建设计文档只会在一定程度上有所帮助,而对于更好或更快速的代码来说却无济于事。 我觉得老板并不真的在乎制造更好的产品,而只是在管理层眼中成为一名好经理。 我能做什么?整整一年,我已经完成了3个月的实际编码,其余时间仅用于制作文档和等待来自客户的错误报告。

3
如何记录实验性或不完整的API,例如@deprecated?
是否有一个与“不赞成使用”相似但又不同的好术语,表示方法或API已存在于代码库中,但由于其实现不完整或可能会发生变化而不应使用?(是的,我知道,这些方法不应该公开,yada yada yada。我没有创造自己的情况,我只是想尽力而为。) 人们有什么建议?实验性的,不完整的,还有其他吗? 如果我正在为该API构建仍在不断变化的javadoc文档,那么我应该使用@deprecated标记还是有更好的约定?对我而言,@ preprecated表示此API很旧,可以使用更新的首选机制。在我的情况下,别无选择,但是API中的某些方法尚未完成,因此不应使用。目前,我无法将其设为私有,但我想在文档中添加明确的警告。

7
文档降级-如何处理?
重要提示:我们有没有问题,有任何的源代码文件。这属于常规代码审核,并且是最新的。我们的问题是开发人员文档(如果愿意,也可以是“外部”),从程序员到程序员的类似博客的小技巧,这些技巧往往一经编写,经常被抛在后面。 我们使用类似Wiki的系统来生成程序员文档 - 程序员为程序员编写的文章,详细描述了特定代码的工作方式。这些维基页面通常包括: API部分设计决策背后的动机(例如;我们做这件丑陋的事是因为这个特定的第三方库希望以这种方式完成工作,因为另一个库...是因为...) 解释我们如何处理特定的常见任务(例如,显示琐碎的弹出窗口,该弹出窗口需要引用适当的应用程序样式,在注册表组件中注册自己,并实现一些接口以便被其他组件自动“扫描”) 良好做法(实际上是主观的,我们确实将这些内容记下来了) 环境配置,所需的工具及其设置 通常,主要与编写代码有关的内容由于其大小和博客文章/类文章的性质而与常规代码文档不符。 问题 就几个月前引入这个系统而言,似乎是个好主意,如今,我觉得它引起的问题比解决的问题多。例如: 人们确实写文章...但是一旦代码更改,Wiki更新就很少跟进 很多草稿文章,是某人匆忙写的,像这样离开 即使文章请求通常来自项目负责人,也几乎从未对其正确性/组成进行过验证-有时会导致质量不佳 通常降解。代码已更改,Wiki保持不变。下次有人寻找信息时,他通常会发现一堆过时,质量低下的东西-并且想知道正在发生什么,他发现的东西是准确的还是(甚至更糟)其中的哪些部分。而本该提供帮助的结果却相反。 目前看来,人们已经意识到了这个问题,包括项目负责人,但是显然没有人愿意为此做任何事情(或者要做更多有趣的事情)。 我最初的想法是将其全部遗忘(在我连续几次被过时的“小费”咬伤之后),但是我想那可能太极端了。一些信息值得注意,有时会读得很好,但是问题仍然存在:如何处理其“最新信息”?它是否以某种方式链接到源代码(因此,当检入文件的更新版本时,文章作者会收到通知,他可能需要修改代码/文章)?有指定人员在日常基础上“监视”它吗?定期清理吗?

4
“文档”的确切构成是什么?
当我们说软件产品的“文档”时,其中包括什么,不应该包括什么? 例如,最近一个问题询问是否将注释视为文档? 但是在很多其他领域,这也是一个有效的问题,其中一些比其他领域更为明显: 手册(显然) 发行说明? 讲解 评论 还有其他吗? 画线在哪里。例如,如果“教程”是文档,是“视频教程”文档,还是其他? 通常,只有对软件中的某些内容进行实施,测试和记录后才能对其进行“完成”。因此,这个问题是,在考虑“完成”某些事情时,我们应该考虑哪些内容作为记录的一部分。 问题来自最近在我们的会议上的客户反馈,表明我们的文档需要更多的“样本”,而我们以前并没有像以前那样善于考虑。 受众:使用我们的数据库,编程语言和相关工具(例如,所述数据库的管理员客户端)的软件开发人员

4
准备源代码移交计划
已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗?更新问题,使其仅通过编辑此帖子来关注一个问题。 4年前关闭。 我们公司即将获得一个巨大产品的源代码。 开始移交时要考虑哪些事项,以确保我们拥有一切并能够在将来维护该产品?

5
什么是“问题域”
我必须为一个学校项目记录我的程序,并且我们有一个称为“问题域”的部分,但是我不知道在本部分中讨论什么。 所以问题是:在问题领域应该讨论什么?

5
替代HTML帮助
当前,我们使用一个名为AsciiDoc的系统,该系统使我们可以使用简单的文本标记创建文档。由此,我们可以生成多种输出格式。我们仅使用pdf输出和chm输出格式。 我想知道是否有chm替代品?我正在寻找的是可以离线使用我们的软件的东西(这很重要,因为我们的很多用户都位于非常遥远的地方)。它应该有一个索引(它可以像带有超链接术语的html页面一样简单),应该是可搜索的,并且它应该具有一种允许从代码中调用特定条目的机制(类似于上下文相关的帮助)。 在这种情况下,针对PDF的两件事是: 上下文相关帮助不是一种选择 通常文件比较大 PDF比上下文相关帮助更适合打印文档 我想要的是使用html。html的唯一问题是,我似乎无法弄清楚如何自动提供关键字搜索(除了浏览器的ctrl + f功能外,我希望更明显)。我似乎也找不到自动生成关键字的超链接索引的方法。由于有section标签,因此上下文相关的帮助将非常简单-我可以简单地将我感兴趣的页面和部分的url传递给默认浏览器,并且该页面应加载到正确的部分。 我的要求听起来像chm一样糟糕-确实如此。我根据chm建模了需求。我不喜欢chm的唯一原因是因为代码使用mapids等与之交互的方式。我宁愿使用存储纯文本列表(为我自动生成)的方式,我的代码可以使用该列表访问文档的上下文相关部分。 我正在构想一个脚本,该脚本将遍历html输出文件并生成一个索引页面,该页面仅包含找到的关键字列表。显然,应该有单词排他机制来忽略诸如“ the”,“ it”,“ is”等单词。这部分将相对容易编写。第二部分将需要某种脚本来将关键字数据库及其在html文本中的位置放在一起。我认为这将是棘手的部分,同时在浏览器中提供搜索机制。 关于替代方案的任何想法将不胜感激。我很想使用托管在某处Web服务器上的Wiki或一组静态html页面,但是我们有一个关键的离线使用要求。只是将html放在本地驱动器上并不能满足我们所需的搜索要求。 编辑: 我设计了采矿业使用的软件。许多地雷都很偏远,无法以任何有意义的方式访问互联网。pdf或html或chm没什么问题(除了它变老了)。如果我可以在正确的位置显示pdf文件(即上下文相关帮助),则可以使用它。我几乎想写自己的东西-基本上它将是便携式Wiki。说到这一点,如果您建议使用便携式Wiki,则必须考虑最终用户,他们可能没有使用此类工具的经验。它必须完全简单。那是chm的美丽,与之合作很痛苦,但最终用户喜欢它。

4
如何管理开源项目的文档?[关闭]
已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗?更新问题,使其仅通过编辑此帖子来关注一个问题。 6年前关闭。 我是一个成长中的开源项目的创建者。目前,我正试图找出管理文档的最佳方法而感到沮丧。这是我考虑过的选项: HTML网站 Github Wiki Github上托管的Markdown文件 将所有文档放在Github中README.md 该文档已经用Markdown编写,我只是想不出如何使它可用。我真的很喜欢Git,因为我可以分支和标记文档,就像可以分支和标记源代码一样。 我可以使用Markdown库将Markdown转换为HTML并将其显示在样式化的网站上。每当发生更改时,我都需要将更改上传到网站,并且很难管理文档的所有不同“标签”。 Github Wiki(据我所知)不会根据您所在的分支进行更改。因此,在任何给定时间,我只能以Github Wiki形式获得文档的“主”版本。 将所有内容放到Github自述文件中非常简洁。我可以进行分支和标记,但是使用起来有点累,而且不便于导航。 我是否缺少一些很棒的解决方案?我还有什么其他选择?

5
为什么要区分功能需求和非功能需求?
我理解两者之间的区别,但是我的同事质疑将标签要求标记为功能性或非功能性(或过渡性)的好处。为什么要这样做呢?他花了两天的时间仔细检查了一个项目的需求清单,但没有发现任何好处,因为最终结果是将文件提交给另一个业务实体,并下达命令“全部完成”。 我担心的是,要求汇总在一个文档中。我试图用实际的方式来解释好处,但是无法出售。如何出售记录哪些需求有效和哪些需求无效的好处。

7
每个程序员都应该保留“经验教训”日记吗?[关闭]
已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗?更新问题,以便通过编辑此帖子以事实和引用的形式回答。 4年前关闭。 每次我完成一个项目时,总会学到一些东西(否则,我不会觉得它很有动力)。但是我记不清所有内容,而且很久以后,我可能会偶然发现上一个项目遇到的相同问题,但是不再解决(或至少尝试了什么)。 那么将其记录在某种日记本中是个好主意吗?我知道写下来的东西就像写文档(并不是每个人都喜欢这样做),并希望我们的记忆在需要时能为我们服务。但是,只要将其记录下来,就可以与其他程序员共享,并从中学到什么。 所以你怎么看?

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.