Questions tagged «documentation»

已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗？更新问题，以便通过编辑此帖子以事实和引用的形式回答。 6年前关闭。 目标是拥有一个在线文档系统，并具有以下主要要求： 将主要用作我们所有应用程序最终技术文档的中间阶段（尽管可能永远不会完成：）。通常按以下方式使用：有人遇到问题，我将其修复，并立即写下该修复程序。现在发生的事情变得无法控制：某人有问题，我解决了，我和某人都很高兴，但是两个月后，其他人也遇到了同样的问题，没有人记得修复的方法。 可从任何地方访问，在我们的apache服务器后面运行 用户/组管理，允许只读/读写/管理员访问 格式不是太重要：纯文本可以，但Wiki样式会更好 便宜或免费 我的一些想法： 只需在文件共享上或通过ssh提供文件即可（缺点：与Windows不太兼容，优点：简单，可以是任何文件类型） 将其保存在SCM中（如上svn / git，idem，但更易于访问和控制访问） Confluence：我们已经使用了Jira，Confluence是否值得？它如何与Jira集成？ 还有什么吗 请不要对这些发表评论，或与其他系统分享您的经验。

11 documentation 

DRY原则（不要重复自己）指出：“每条知识都必须在系统中具有单一，明确，权威的表示形式。” 在大多数情况下，这是指代码，但它通常还扩展到文档。 据说每个软件系统都有一个体系结构，无论您是否选择它。换句话说，您构建的软件具有结构，而“已构建”结构就是软件的体系结构。 由于构建的软件系统具有体系结构，因此创建该系统的体系结构描述是否违反DRY原理？ 毕竟，如果您需要了解架构，那么您始终可以只看一下代码...

11 agile  documentation  architecture  dry 

按照目前的情况，这个问题并不适合我们的问答形式。我们希望答案得到事实，参考或专业知识的支持，但是这个问题可能会引起辩论，争论，民意调查或扩展讨论。如果您认为此问题可以解决并且可以重新提出，请访问帮助中心以获取指导。 7年前关闭。 在起草项目建议书时，您是否使用任何标准模板？ 应该包括哪些功能/信息？有什么好包含的？我应该输入哪种样板信息？ 您发现任何设计模式或概念特别有用吗？

11 project-management  business  management  documentation 

我们的软件有几个类，应该通过反射来动态找到。这些类都有一个带有特定签名的构造函数，反射代码通过该签名实例化对象。 但是，当有人检查是否引用了该方法时（例如，通过Visual Studio Code Lens），则不计入通过反射进行的引用。人们可能会错过他们的引用，并删除（或更改）表面上未使用的方法。 我们应该如何标记/记录打算通过反射调用的方法？ 理想情况下，应以同事和Visual Studio / Roslyn以及其他自动化工具都“看到”该方法旨在通过反射调用的方式进行标记。 我知道我们可以使用两个选项，但都不太令人满意。由于Visual Studio找不到引用，因此： 使用自定义属性，并使用此属性标记构造函数。 问题在于，属性属性不能是方法引用，因此构造方法仍将显示为具有0个引用。 不熟悉custom属性的同事可能会忽略它。 我当前方法的一个优点是反射部分可以使用该属性来查找应调用的构造函数。 使用注释来证明打算通过反射调用方法/构造函数。 自动化工具会忽略评论（同事也可能会忽略评论）。 XML文档注释可以用于具有Visual Studio计数的额外参考方法/构造： 让MyPlugin是它的构造经由反射调用的类。假设调用反射代码搜索采用int参数的构造函数。以下文档使代码透镜显示了具有1个引用的构造函数： /// <see cref="MyPlugin.MyPlugin(int)"/> is invoked via reflection 存在哪些更好的选择？ 标记要通过反射调用的方法/构造函数的最佳实践是什么？

11 c#  .net  documentation  reflection 

当我为自己编写小型脚本时，我会将代码和注释高度堆积在一起（有时注释比代码更多）。我要说的很多人都说，即使这些脚本是个人的，我也应该记录这些脚本，以便如果我确实出售它们，我将做好准备。但是注释不是文档形式吗？ 这不是吗： $foo = "bar"; # this is a comment print $foo; # this prints "bar" 被视为文档，特别是如果开发人员正在使用我的代码？还是认为文档不在代码本身之外？

11 documentation  comments 

在我看来，单元测试用例本身就是代码的文档。我的公司希望我在单元测试用例的顶部编写详细的Java文档注释。是否有必要这样做？你这样写评论吗？

11 unit-testing  documentation 

我们创建了一个供外部开发人员使用的商业库和代码示例。我们有（封闭的，可供注册用户使用）文档，其中广泛解释了如何使用该库。 许多开发人员是首次使用，因此会遇到很多基本错误。 在错误日志中包含指向文档的链接是否合适？可能的不利之处是什么？我可以预见一些，但似乎有可能克服以下问题 文档URL已过期 最新文档中未反映的特定于版本的错误 还有其他问题，我们通过将开发人员发送给无关的文档来浪费开发人员的时间 在我的意思示例下面，添加粗体字是个好主意吗？ [错误]无法在独立项目上执行目标org.apache.maven.plugins：maven-archetype-plugin：1.2.3：generate（default-cli）：所需的原型不存在（com.example.library。 archetypes：library-archetype-blank：1.2.3.0）->请参阅http://example.com/docs/setting-up-an-archetype了解更多信息和可能的故障排除

10 documentation  api-design  error-handling  error-messages 

我是一名业余开发人员，到目前为止，我的所有程序都很简单，可以在代码中进行记录。在阅读代码时，很清楚我在做什么和这样做（我的标准测试是6个月后查看代码，并在初读时了解所有内容-我的内存跨度很短）。 我现在面对的是一个程序，该程序超出了我记住这些程序之间各种交互的能力。 代码本身 数据库中的索引 各种模块之间的交互（“工作人员”核心代码和“库”模块） 我当前的文档是一个白板，其中有各种各样的框和箭头，它们指向代码，数据库索引，正在执行的操作，状态更改等。仅供参考，一团糟： 我的问题是，对于更复杂的产品的文档记录，是否存在一套标准的或最佳实践的最佳实践集（命名为这是一组以特定名称分组的实践）。 我应该寻找什么关键字（对“文档软件体系结构标准”的一般尝试以及类似的变体，通常会导致用于工作流或建筑体系结构CAD系统的软件）。 我还希望对高级描述没有通用的最佳实践，并且每个人都可以建立自己的哲学。

10 architecture  documentation 

我是该项目的唯一开发人员，就像其他软件项目一样，将来可能会被其他人采用。 假设我使用模式X来实现功能A。在开发和完成功能之后，我意识到可以使用我刚刚学习的模式Y来实现相同的功能。但是功能A运行良好，并且从X到Y的重构既耗时又无济于事。 然后是实现功能B的时候了。它与A相似，但是这次我想借此机会使用模式Y。我对最终结果感到满意，比使用功能A更好，但是现在我的代码使用了两个具有相似特征的X和Y不同的图案。 但是没有真正的理由使用不同的模式，除了以下事实：构建功能AI的技能不足以使用与功能B相同的模式。 请注意，此问题不是针对给定问题选择正确的模式；这是在代码库中共存的两种模式，用于解决类似的问题，如果有足够的时间进行重构，则可以将其减少为一种。 该代码闻到了吗？ 保持这样的源代码有什么缺点？ 我应该只使用一种模式吗？即重构A以使用Y或在编写B时继续使用X？ 从源头上，我该如何传达出针对相似功能存在两种不同模式的原因基本上是没有原因的？ 我是否担心下一位开发人员对我的代码的看法？

10 design-patterns  refactoring  documentation 

您希望在github自述文件中看到哪些信息？ 一切都应该放在自述文件中吗？即 介绍 安装 版本号 用户指南 实作 测试中 相关资源 还是应该将某些内容放进自述文件（简介，安装，版本）中，而其他信息最好放在Github Wiki中？

10 documentation  github 

我曾经是要求XML注释用于文档的爱好者。从那以后，我改变了主意，主要有两个原因： 像好的代码一样，方法应该是不言自明的。 实际上，大多数XML注释都是无用的噪声，不会提供任何附加值。 很多时候，我们只是使用GhostDoc生成通用注释，这就是我所说的无用噪声： /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } 对我来说，这很明显。话虽如此，如果要包含特殊说明，那么我们绝对应该使用XML注释。 我喜欢这篇文章的摘录： 有时，您将需要写评论。但是，这应该是例外而不是规则。仅当注释表示无法用代码表达的内容时，才应使用注释。如果要编写简洁的代码，请努力消除注释，而改写自记录代码。 我认为我们仅应在代码不足以自行解释时使用XML注释吗？ 我相信这是一个很好的示例，其中XML注释使漂亮的代码看起来很难看。需要上这样的课... public class RawMaterialLabel : EntityBase { public long Id { get; set; } …

10 .net  programming-practices  development-process  documentation  comments 

目前，我们在当前项目中使用的是敏捷方法，并且我们有很多类似的故事： 作为助理，我想向客户退款，以便他们可以在要求时获得一些退款 作为客户，我想付款以购买商品。 到目前为止，我们的工作方式是在每个冲刺中挑选最重要的故事，并将其详细阐述为许多正式的需求规格（我们将一些在相同规格中相似的故事归为一组）。根据故事的不同，它可能只是屏幕上的按钮或整个工作流程。 现在的问题是，因为故事太多，对于系统中与故事相关的任何部分，现在还不清楚。 它可以在开发人员时发挥作用，开发人员的每一次冲刺都只是获得一个规范，概述他们需要做的事情和需要进行的更改。但是就维护此故事列表和进行测试而言，它开始变得很难跟踪错误，并且通常只是维护规范，因为屏幕上的一项功能可能已经记录在许多不同的地方按故事拆分。 根据故事写规范是个好主意吗？我们写故事的方式有误吗？

10 agile  documentation  requirements  user-story 

我目前工作的一般方法是- 尽可能避免记录 仅在有其他团队需要时记录 只是为了澄清，我不是指代码文档-我们这样做是指围绕设计过程的所有文档-如果是UML或DB Schema，类图和带有规范等的word文档。 我将列出老板未记录的原因： 这很耗时-专注于实施 如果设计更改-那么文档应该更改，麻烦倍增 最后，您只得到数百页，没有人想要阅读，也没有人真正编辑，所以到了时间，它就会过时了 这很痛苦-没有人真的想要这样做 现在我意识到我们的工作速度更快，但是我也记得花时间来到这里，直接跳到一些旧代码，什么都不懂。 实际上，我仍然没有得到大部分的旧代码，有时当我进入时，我会看到许多来自不同开发人员的补丁试图进行细微调整。 我确实认为，缺少文档会促进此类补丁，并且从广义上讲，缺乏对系统的理解。 我的问题是： 我们如何平衡文档，以便在团队之间增进持续的知识并且仍然快速有效？

10 documentation 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 5年前关闭。 我目前所在的团队拥有相当高的营业额，成员通常移至同一公司的不同项目。当前，我们对新成员的“培训”是将他们与主要联系人（通常是完成培训的最新人员）配对，后者将为他们提供动手实践经验，并将询问更多的高级开发人员，如果新聘的员工向导师咨询不知道 它为新员工提供了快速参与的机会，并向指导者提出挑战，以提高他/她对系统的理解。 但是，正如您可以想象的那样，这种培训方式非常耗时，并且不能提供很好的知识传递（误解不断扩大，差距不断扩大）。 我的任务是为未来的新员工生成文档和培训材料。我已经偶尔进行过技术写作，但这是针对最终用户的，它具有很多截屏，非常具体，并且花费大量时间来完成。 为新员工创建新文档被认为是低优先级的，我目前只有大约40个小时的工作时间。以我目前编写技术文档的方式来记录系统，几乎不会在40小时内刮擦表面。特别是考虑到我不仅必须记录有关代码库的内容，还要记录有关部署和支持的内容。 如何快速编写文档以使新员工尽快更新，而又不花费大量时间编写文档？ 附加信息： 目前，我们既有Wiki，也有一些培训文档，但是两者都很少。

10 documentation  training 

我是正确编写代码的支持者，并且我很清楚其可能存在的弊端。这超出了这个问题的范围。 考虑到我在Visual Studio中非常喜欢IntelliSense，我喜欢遵循为每个公共成员添加XML注释的规则。 但是，存在一种形式的冗余，即使像我这样的过多评论者也会对此感到困扰。以List.Exists（）为例。 /// <summary> /// Determines whether the List<T> contains elements /// that match the conditions defined by the specified predicate. /// </summary> /// <returns> /// true if the List<T> contains one or more elements that match the /// conditions defined by the specified predicate; otherwise, false. /// …

10 documentation  comments  intellisense