Questions tagged «documentation»

软件开发公司的主要目标之一是提高其总线系数。Google在一次演讲中也倡导了这一点。 这意味着您应该以一种方式对所有内容进行编码和文档编制，以确保明天您要在公共汽车上运行时，项目仍然可以继续进行。换句话说，您应该使自己很容易被具有类似技能的其他程序员替换。 可替换，这是否违背了开发人员的利益？在这本书中，有48条权力定律第11条规定，您应该设法使人们依赖于您，以便获得权力，然后将其转化为金钱奖励。 除了这种情况，您需要自己准备一些文档才能在暂停6个月后继续进行项目，开发人员和软件公司之间显然存在利益冲突。 因此，作为一名程序员，您应该为所有人真正编写出色的文档和易于阅读的代码吗？还是应该以一种可以完成工作的方式编写代码和文档，并且您自己可以理解它，但是另一个人可能很难理解它？

48 documentation  clean-code 

即使编写最基本的文档，似乎也存在反感。我们的项目自述文件是相对裸露的。在文档中甚至没有更新的依赖项列表。 我在行业中没有意识到让程序员不喜欢编写文档的东西吗？如果需要，我可以键入文档的段落，那么为什么其他人那么讨厌呢？ 更重要的是，我如何使他们相信写文档会为我们节省时间和日后的挫败感？

47 documentation  teamwork 

在编写代码时，我遇到了许多与队友一样的挑战，并且编写了一些有用的函数和类，它们也是如此。如果能保持良好的沟通，我会听说有人将一些很棒的东西组合在一起，六个月后，当我需要它时，我可能会记住它并调用该函数，从而节省了时间。如果我不记得它，或者从不知道它，我可能会重新发明轮子。 是否有记录此类事情的特殊实践？您如何使它们容易找到？ 如果您的团队没有这样的文档，您如何查找车轮是否已经存在？ 编辑： 到目前为止，除了一个答案以外，所有答案都与理想情况有关。因此，让我总结一下这些解决方案：文档和通讯；这些都是很棒的事情，但是它们依赖于程序员有时间（和技能）来编写文档，参加会议，做笔记并记住一切。 到目前为止，最流行的答案（Caleb答案）是程序员无法使用的唯一答案，它没有文档和会议的能力，并且只做一件事：编程。编程是程序员的工作，是的，一个优秀的程序员可以编写文档，进行单元测试等，但是让我们面对现实吧-我们大多数人都喜欢编程而不是文档。他的解决方案是程序员识别可重用的代码并将其拉到其自己的类或存储库等中，并且由于它是孤立的，因此变得可查找并简化了使用它的学习曲线。这是通过编程来完成的。 从某种角度来说，我是这样看的：我刚刚编写了三个函数，我想到其他人应该也了解它们。我可以记录它们，编写它们，在会议上宣布它们，等等。-我可以做，但是这不是我的强项-或....我可以将它们提取到一个类中，命名好，使它们像一个黑盒子，然后将其粘贴到其他类文件所在的位置。然后，一封简短的电子邮件宣布它很容易。其他开发人员可以扫描代码并更好地理解代码，而不是使用他们无法完全理解的代码中使用的隔离功能-删除上下文。 我之所以喜欢它，是因为这意味着拥有一组具有良好名称的类文件以及具有良好名称的方法，是一个很好的解决方案，可以通过良好的编程来实现。它不需要开会，并且可以减轻对详细文档的需求。 在这种情况下，还有其他想法吗……针对孤立的且时间紧迫的开发人员？

43 documentation  teamwork  team  code-reuse 

我发现自己（希望）在以下类型的代码（C ++）文档中写了有用的注释： The reason we are doing this is... 之所以使用“我们”而不是“我”，是因为我经常在学术论文中经常偏爱“我们”。 所以这是问题。在编写代码时是否有充分的理由比另一个更好： 使用“我们”：我们这样做的原因是... 使用“我”：我这样做的原因是... 请使用我的名字：这样[my name]做的原因是... 被动语态：这样做的原因是... 都不：这样做是因为... 我之所以选择＃1，是因为我习惯于以这种方式编写，但是文档不是针对作者的，而是针对读者的，所以我想知道添加开发人员名称是否有帮助，或者是否只是添加了另一件事需要在维护代码时进行更改。

41 documentation 

我学校的CS程序避免了任何有关面向对象编程的问题，所以我一直在自己做一些阅读来补充它-特别是Bertrand Meyer的面向对象软件构造。 Meyer反复指出，类应隐藏尽可能多的有关其实现的信息，这是有道理的。特别是，他反复指出，属性（即类的静态，非计算属性）和例程（与函数/过程调用相对应的类的属性）应该是无法区分的。 例如，如果一个类Person具有属性age，他断言，它应该是不可能告诉，从符号，是否Person.age相当于国内喜欢的东西return current_year - self.birth_date或干脆return self.age，其中self.age已被定义为一个常量属性。这对我来说很有意义。但是，他继续声称以下内容： 将设计类的标准客户端文档（称为类的简称），以免透露给定功能是属性还是函数（在可能的情况下）。 即，他声称即使是该类的文档也应避免指定“ getter”是否执行任何计算。 这，我不明白。难道文档不是将这种区别告知用户的重要场所吗？如果我要设计一个包含Person对象的数据库，那么知道是否Person.age是一个昂贵的调用就不重要了，那么我可以决定是否为其实现某种缓存？我是否误解了他的意思，还是他只是OOP设计哲学的一个极端例子？

39 design  object-oriented  documentation  performance 

什么是技术规格？它们是否与设计文件相同？如果没有，有什么区别和一些例子？

38 documentation  specifications 

我们正在尝试将项目文档流程从Google文档移至一组自托管的Git存储库。 文本文档对Git足够友好，因为我们通常不需要任何精美的格式，因此我们仅将所有内容转换为multimarkdown，并可以在复杂情况下嵌入LaTeX。 但是电子表格的故事大不相同...是否有一种类似于版本控制系统的扩展格式（最好与Markdown一样易于阅读）？ “友好格式”：Git与格式兼容（不适用于XML），并且生成易于理解的差异（可以进行涉及外部工具的额外配置）。 显然，Markdown风格允许建立静态表，但我希望能够使用诸如此类的东西SUM()（请注意CSV也存在相同的问题。）没有所见即所得的功能，但是可以提供不错的编辑器/工具支持很好 更新：请仅提供Linux友好的答案。没有MS Office资料。

35 version-control  documentation  tools  linux 

我公司正在寻求改善其市场研究数据管理。 当前的数据管理风格： “嘿，金宝，我们的WhatZit 2.0的图片在哪里？ “是的，我记得那个家伙发给那家公司的电子邮件，给我几分钟搜索我的Outlook” “谁拥有重要竞争对手产品目录的最新副本？我的是2009年生产的。” ...“ Colleen这样做，而且她正在休产假。您必须打电话给她以获取她的工作站密码...” 所需的数据管理风格： 数据按主题（法律，经济，工业，竞争对手）整理得井井有条 对于每个主题，多种媒体类型存储在一起（公司产品图片，新闻稿，联系信息），但仍按类型整齐地排序 数据编辑历史 公用访问（无数据孤岛） 我当时正在考虑建立一个部门Wiki，以供所有用户访问。它似乎满足了以上四个条件，但是我有点担心它对于更高级的功能（如图像库，文章格式设置等）的用户友好性（阅读：对于非技术人员而言是可以理解的）。 这里有没有人为非IT人士设置的Wiki，并且它没有着火，变成鬼城或像Geocities？ 额外的问题：您能看到选择MediaWiki（或任何其他Wiki）解决此问题时有明显的缺点吗？ （我希望你们中的某些人以前会遇到此问题，并且可以提供一些见解...）

35 documentation  cms  wiki 

我作为团队的成员在没有内联文档，也没有技术文档的现有应用程序上工作。当我一直在处理应用程序的各种错误报告时，我为自己写了一条面包屑的痕迹-各个地方的错误号，以便下一个开发人员可以参考该错误号以查看发生了什么。 因此，我的问题是： 记录此代码的最有效方法是什么？我应该在接触该区域时记录下来（如果需要，可以使用病毒方法），还是应该自己从每个部分进行记录，而不遵循分支到应用程序其他区域的路径？我应该在以前不存在的地方插入行内注释吗（担心我最终可能会错误地识别代码的作用）？ 您将使用哪种方法来准确，快速地为没有现有内联文档或内联引用外部文档的大型应用程序提供文档？

35 documentation  language-agnostic  methodology 

我目前是政府承包商的实习生，并且（令人讨厌的不可避免）感觉到Word是软件开发过程中的实际标准。 它的二进制格式使我很难像以前在代码库上进行协作的方式在文档上进行协作。使用纯文本标记（使用LaTeX，Markdown，ReStructured Text 等语言））可以使diff友好的文档与开发人员的正常工作流程配合使用。对于不支持该语言的注释（例如Markdown），有许多现有的解决方案允许基于代码库的协作注释（例如GitHub，Bitbucket），可以轻松地将其应用于包含标记的其他纯文本文件。 我了解与技术不熟练的管理人员合作的必要性，需要对所有内容都使用某种图形界面，但是大多数这些格式都存在此类界面。例如，LaTeX有一种名为“ LyX”的“叉子”，可将图形前端放入纯文本形式的类似LaTeX的语法中。尽管该文件在编辑时主要是图形化的，但仍是差异友好的。（它甚至还具有Word样式的注释。）这些解决方案中的许多都可以代替Word使用，并且绝大多数是免费的或开源的。 但是，我们甚至将Word用于我们自己的内部文档，其他人看不到。我们在大部分职业中都使用文本进行工作-为什么文档如此特别？除了琐碎的“我们没有更好的东西，现在我们被困在这里”之外，还必须有支持这种决定的理由。在使用纯文本文档代替其他口语化（且功能上可能不够强大的文档）的方法来代替纯文本文档时，软件开发过程会面临哪些挑战？ 由于原因会有所不同，因此应该分别针对这两个紧密相关的场景进行回答。 从一开始就使用纯文本文档 随着时间的推移迁移到纯文本文档

33 development-process  documentation 

人们什么时候开始编写自述文件？ 似乎几乎所有程序都具有此文件，而不管格式如何。 该文件是否有任何书面记载的首次使用？

32 documentation  terminology  history 

有一些很好的示例，这些示例都记录了很好的代码，例如java api。但是，公共项目（例如git和公司的内部项目）中的许多代码都没有很好的文档记录，并且不是很新手。 在我所有的软件开发工作中，我不得不处理文档记录不佳的代码。我注意到以下情况- 代码中很少或没有注释。 方法和变量名不是自描述的。 很少或没有文档说明代码如何适合系统或业务流程。 雇用不良的开发者或不指导好的开发商。他们不能编写简单干净的代码。因此，包括开发人员在内的任何人都很难或不可能编写代码。 结果，我不得不阅读大量代码并与许多人交谈以学习事物。我觉得这浪费了大家的时间。它还为项目的新手带来了KT /知识转移会话的需求。 我了解到，由于以下原因，文档没有得到应有的重视： 懒惰。 开发人员只喜欢编写代码就什么都不喜欢。 就业保障。（如果没有人能轻易理解您的代码，那么您可能就很难被替换。） 艰难的截止日期几乎没有时间记录在案。 因此，我想知道是否有一种方法可以鼓励和执行公司或项目中的良好文档规范。无论项目的复杂性如何，用于为任何项目的系统和代码创建体面文档的策略是什么？有什么很好的例子，说明什么时候需要最少的文档或根本不需要文档？ 恕我直言，我认为我们应该在项目交付后对文档进行审查。如果它不简单，简洁，说明性和用户友好性，则开发人员或技术文档工程师将对此负责，并负责对其进行修复。我既不希望人们编写大量文档，也不希望它像第一本书一样对用户友好，但是我希望它消除了数小时的分析和浪费的KT会话。 有没有办法结束或减轻这种疯狂？也许是“文档驱动的开发”？

26 programming-practices  development-process  documentation  source-code  sdlc 

在我的工作场所，我们面临的挑战是“敏捷”常常意味着“含糊的要求，不良的接受标准，好运！” 我们正在努力解决这一问题，作为一项总体改进工作。 因此，作为其中的一部分，我建议我们生成设计文档，这些文档要超出用户故事级别，并且能准确反映对系统中给定功能的效果进行初步调查的结果，并包括对我们所遇到问题的解答问生意。 有没有有效的标准呢？ 我们目前面临的情况是，一项新功能可能会影响我们的“大泥巴”系统中的多个区域，并且由于这种技术债务，估计开始上升。希望更多周到的设计过程可以提供帮助。

25 design  agile  documentation 

行为驱动的开发及其标志性的“ Given-When-Then”场景语法最近被大肆宣传，因为它有可能用作软件功能评估的边界对象。 我绝对同意，Gherkin或您喜欢的任何功能定义脚本都是商业可读的 DSL，并且已经提供了这样的价值。 但是，我不同意它是非程序员可写的（就像Martin Fowler一样）。 有人对非程序员编写的场景，然后由开发人员提供的场景有说明吗？ 如果确实对缺乏可写性达成了共识，那么您是否会看到一种工具的问题，该工具可以从实际测试中生成业务可读的场景，而不是从场景开始并对其进行检测。 更新：关于“场景生成器”工具，它当然不会神奇地猜测业务语言;）但是，就像我们当前使用正则表达式匹配器以自顶向下的方法（在抽象维度上）创建测试一样，我们可以使用字符串构建器以自下而上的方式创建方案。 “仅给出想法”示例： Given I am on page ${test.currentPage.name} And I click on element ${test.currentAction.element} …

24 documentation  bdd  documentation-generation  business-rules 

我从事一个项目已经有几年了，并且我开始收集一个不错的用户群。我已经创建了一个项目页面，其中包含一些基本文档，但实际上，这仅是一个FAQ。我知道我需要改进它，以便它对新用户和高级用户都提供更多信息，并且这是下一发行版的任务清单中的下一个。 但是，下一个版本具有用户群渴望获得的功能。我已经准备好立即发布它，它已经打包并可以使用了。我只需要将其部署到适当的分发服务。 要点。这些功能对我的用户很重要，但是文档对我很重要。我应该等到重写文档后再发布吗？我当前的用户群足够了解如何使用新功能，因此我不必担心。由于我的空闲时间有限，因此可能需要花费几周才能完成文档，但是如果我让他们再等待的话，社区就会把我烤死。 客户在这种情况下正确吗？对于现有用户而言，梦幻般，直接的功能是否应该优先于针对新用户的强大文档？ 更新：哇，这么多优质的回复！您确实帮助我更好地了解了我应该如何与项目及其用户进行交互和支持。太感谢了！

23 documentation