Questions tagged «documentation»

我真的很喜欢编程语言设计。有时，我认为我的语言项目及其潜在用户将从全面的标准文档中受益。我看过许多语言标准，从非常正式的（C ++）到相当非正式的（ECMAScript），但是我无法真正理解如何分解内容并组织这样的文档，即使我认为我总体上很擅长技术写作。 我应该像是一本很长的教程，还是更像是一份正规的数学论文来编写它？如果我正在与参考实现一起开发它，如何使其保持最新状态？我是否应该放弃并将实现和文档视为事实上的标准？此外，拥有标准真的有任何重大好处吗？要求标准是否意味着该语言不必要地复杂？

16 programming-languages  documentation  standardization 

我正在为客户设计必须有效且适合用途的产品。 它基于LAMP堆栈（PHP / Cake）构建，因此具有GPL，MIT，PHP，APACHE许可证： “按现状”，没有任何明示或暗示的保证或条件，包括但不限于标题，非侵权，可贸易性或特定用途的适用性的任何保证或条件。您应自行负责确定使用或重新分发作品的适当性，并承担与您根据本许可行使许可有关的任何风险。 我的理由是我的产品有效且适合以下用途： 签名的UAT文档证明其有效性和适用性。 堆栈被开发人员，行业和最终用户（netcraft，gartner等统计数据）广泛使用，以至于人们普遍认为该堆栈适用于目标。（即我们可以在一定程度上忽略保修免责声明中的适用性声明） 这是有效的观点吗？我可以声称我的软件适合使用吗？

15 licensing  documentation  specifications 

我目前正在与我所在大学的一位教授合作，为我学院提供的软件工程和Capstone设计课程开发新课程。 直到最近，这两个课程都只使用瀑布模型，因此，学生们大部分时间都在写冗长的报告。在我施加很大压力之后，我的教授决定在上学期将Scrum纳入软件工程课程。 本学期的前半段仍然是瀑布式的，学生们撰写了40页的设计报告和软件规格文档。学期中，所有团队都必须发布其应用程序演示。那时，课程切换到Scrum，进行了两个为期3周的冲刺。现在，我们正在尝试找出如何完全消除瀑布并创建完全基于Scrum的课程。 不幸的是，我们在Scrum和学生之间遇到了一些不兼容性： 对于学生来说，每天召开Scrum会议几乎是不可能的。即使在上课期间，由于教授通常是在讲课，所以学生召开Scrum会议也不方便。 由于学生缺乏经验，因此无法准确地预测要花费多长时间，因此很难估计积分/小时。 Scrum与全职，位于同一地点的开发人员最适合，但学生都不是。学生最多每周奉献15至20个小时的课程，组织工作会议可能非常困难。团队最多可以有10个学生（并且总是有一两个懒人）。 教授们渴望文档！我还没有听说过Scrum的任何报告，只有积压的工作量和燃尽图（我不确定这是否足以使学者安心）。 学生通常认为敏捷的意思是“立即跳入并开始编码而无需回头”。这导致了一些可以想象的最可怕的代码。因此，我正在寻找一种方法来执行适当的设计，而不需要50页的文档或一堆UML图。 鉴于这些问题，您如何看待我和我的教授如何使Scrum在学术环境中发挥作用（并且我们一开始甚至应该为Scrum烦恼）？此外，教导瀑布模型是否仍然有价值？ 预先感谢您的任何反馈！

15 agile  scrum  documentation 

关闭。这个问题是题外话。它当前不接受答案。 想改善这个问题吗？ 更新问题，以使它成为软件工程堆栈交换的主题。 6年前关闭。 我正在寻找用于组织和维护项目内部文档，规范，要求等的软件。当前，我们将所有文档以大量MS Word DOC文件的形式存储在源代码控制存储库中，这为我们提供了版本控制，这很好。但是您无法搜索此信息，无法在它们之间创建链接，进行分类，进行协作。 要求，偏好： 客户端上零安装（基于Web）。 文档版本控制。 文档注释。 文档链接。 完整搜索（所有文档）。 MS Word（* .doc）导入\导出。 所见即所得的文本编辑器。 到目前为止，我已经发现并尝试过的系统： MediaWiki XWiki 合流

15 project-management  documentation  knowledge-management  knowledge-base 

如果JSON代表JavaScript对象表示法，那么当您说JSON对象时，您不是真的在说“ JavaScript对象表示法对象”吗？ 说“ JSON字符串”会更正确吗？ 还是简单地说JSON更正确？（如“这两个服务在它们之间传递JSON”中所述。）

15 documentation  grammar  json 

关于编写规范，我有几个问题，它们是： 在编写软件规范时，在“用户需求定义”主题下，我们仅需指定“功能”和“约束”？ “用户界面”属于“功能”还是“约束”？ 软件可以细分的主要关键领域（要求）有哪些（例如UI）？

15 documentation  requirements 

（对于将来的开发人员）多少技术文档就足够了？在小时编码和小时记录之间是否存在适当的比例？ Papadimoulis认为您应该 生成所需的文档数量最少，以促进更多的了解， 那是一个好的指导方针，还是我应该创建一些具体的东西？

15 documentation 

我在一家控制系统公司工作，主要工作是SCADA和PLC以及其他控制系统。 除非决定创建内部项目管理和评估系统，否则软件开发实际上不是公司要做的事情。 这个项目最初是由来这里从事软件工作的人们承担的，我们大多是初级的。 该项目起初很小，所以我们只记录设计，数据库等内容，但我们从未真正同意编码格式/惯例。 我们开始使用StyleCop来确保我们已编写了完整的代码，但是我认为我们需要一个正式的文档来编写编码约定/实践，以便我们可以继续制定一个良好的标准，并且如果将来还有其他重要的开发工作（无论谁在此工作），具有良好的底板。 问题就出在这里，我不知道如何起草编码惯例和标准的文档，我所能想到的只是良好实践与不良实践的例子（例如，在命名变量，避免匈牙利符号等情况下的驼峰案例），我们都是能干足够的程序员（显然），但是我们只是没有关于这类东西的章程。 首先，我的问题是：好的编码标准文档的关键方面和内容是什么？

15 programming-practices  documentation  coding-standards  standardization 

我正在寻找有关Entity，Business Logic和Data Access类的信息丰富的类文档格式。 我从这里发现以下两种格式 格式1 ///----------------------------------------------------------------- /// Namespace: <Class Namespace> /// Class: <Class Name> /// Description: <Description> /// Author: <Author> Date: <DateTime> /// Notes: <Notes> /// Revision History: /// Name: Date: Description: ///----------------------------------------------------------------- 格式2 // =============================== // AUTHOR : // CREATE DATE : // PURPOSE : // SPECIAL NOTES: // …

15 c#  documentation  comments 

我们公司正在将大量手动业务流程（以及相关的机构知识）转换为新的企业软件。该项目的进展非常顺利，但是随着我们的进行，很明显，业务和开发方面的术语和定义存在很多混乱。 我已经知道Evan关于形成一种普遍存在的语言的争论已有一段时间了，但这是我第一次需要正式记录它们。当我环顾四周并尝试思考在哪里/如何记录我们的UL条款时，我有点迷失了。 其他公司如何记录无所不在的语言？这只是一个Wiki风格的词典吗？是否有用于此目的的工具？

14 documentation  domain-driven-design 

最近，我偶然发现了不可变对象的实用性，例如，如果将元素传递给构造函数并且类应该是不可变的，那么如果它们本身不是不可变的，则必须复制这些元素。 这需要对我的项目进行大量检查或了解，因为如果我有 public A(B foo) 而且B不是一成不变的，A我必须复制B。现在想象一下B似乎是不变的，但是它本身在构造函数中具有可变的类，依此类推。 如果类在Java中是不可变的，是否有记录的标准或最佳实践？看来@immutableJavadoc中没有关键字。 该@Immutable注解似乎有什么东西对汽车类生成完全不同的，而不是标准的Java的一部分。

14 java  documentation  immutability 

已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗？更新问题，以便通过编辑此帖子以事实和引用的形式回答。 4年前关闭。 我目前正在学习Python，这不是我的大学课程的一部分。在一次采访中有人问我为什么选择Python，我回答说它很容易学习并且文档写得很好。面试官没有回答这是否足够充分的理由。他看上去很有说服力，但我不确定。 编写良好的文档以及易于学习是否是选择脚本语言的足够充分的理由？还是我应该详细说明Python库的可用性和更大的Python用户群？ 请注意。不需要Python。该公司致力于Ruby-on-rails。我的简历中有Python，我认为面试官只是想知道我在选择编程语言时重新考虑的考虑事项。

14 learning  python  interview  documentation 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 4年前关闭。 与没有项目设计或体系结构文档的开源项目如何成功一样？问题，我很好奇：为什么如此众多的库缺少最终用户文档？ 我的看法是这样的： 大多数人都认为阅读源代码比编写源代码更困难。 如果没有文档，则必须阅读该库的源代码才能使用该库。 因此，使用未记录的库比从头开始重新创建库要耗费更多的工作。 因此，如果您想让人们使用您的图书馆，那么最好确保它已被记录在案。 我知道许多开发人员不喜欢编写文档，并且我同意这可能是乏味的工作。但这是必不可少的工作。我什至要说，拥有一个好的文档比拥有世界上最好的程序员接口更重要。（人们一直使用糟糕的库；很少使用未记录的库） 哦，请注意，当我说文档时，是指真实的文档。不是Sandcastle / Javadoc / Doxygen样板。

14 documentation 

我们正在将测试过程集成到SCRUM过程中。我的新角色是编写我们的Web应用程序的验收测试，以便稍后使它们自动化。我已经阅读了很多有关如何编写测试用例的文章，但是没有一个给我实用的建议来编写用于复杂Web应用程序的测试用例，相反，它们引发了我发现难以应用的矛盾原则： 测试用例应该简短：以CMS为例。简短的测试用例易于维护，并且易于识别输入和输出。但是，如果我想测试一系列的操作（例如，添加文档，向另一个用户发送通知，其他用户答复，文档更改状态，用户收到通知），该怎么办？在我看来，测试用例应该代表完整的场景。但是我可以看到这将如何产生明显复杂的测试文档。 测试应该标识输入和输出：如果我的表单很长，包含许多相互作用的字段，并且行为不同，该怎么办。我要为所有内容编写一份测试，还是为每项编写一份？ 测试用例应该是独立的：但是如果测试上传操作要求连接操作成功，我该如何应用呢？它如何适用于编写测试用例？我应该为每个操作编写一个测试，但每个测试都声明其依赖关系，还是应该为每个测试重写整个场景？ 测试用例应轻松记录在案：此原则特定于敏捷项目。那么，您对如何实施这一原则有何建议？ 尽管我认为编写验收测试用例会很简单，但我发现自己对要做的每一个决定都不知所措（仅供参考：我是开发人员，而不是专业的测试人员）。所以我的主要问题是：为了编写适用于复杂应用程序的可维护验收测试用例，您有什么步骤或建议。谢谢。 编辑：澄清我的问题：我知道验收测试应该从需求开始，并将整个应用程序视为一个黑匣子。我的问题与编写测试文档，确定测试用例，处理测试之间的依赖关系的实际步骤有关...对于复杂的Web应用程序

14 testing  documentation  acceptance-testing 

我目前正在使用两个系统编写代码文档（上午使用C ++）： 使用Doxygen格式在代码旁边添加有关方法和类成员的文档。在服务器上，Doxygen在源上运行，因此可以在Web浏览器中看到输出 概述页面（描述一组类，应用程序的结构，示例代码等）被添加到Wiki中。 我个人认为这种方法很简单，因为有关成员和类的文档确实与代码接近，而概述页面确实很容易在Wiki中进行编辑（并且还很容易添加图像，表格等）。Web浏览器允许您查看两个文档。 我的同事现在建议将所有内容都放入Doxygen，因为我们可以创建一个包含所有内容的大帮助文件（使用Microsoft的HTML WorkShop或Qt Assistant）。我担心的是，编辑Doxygen样式的文档要困难得多（与Wiki相比），尤其是当您想要添加表，图像等时（或者Doxygen的“预览”工具不需要您生成）代码才能看到结果？） 大型开源（或封闭源）项目使用什么来编写其代码文档？他们还将Doxygen样式和Wiki分开吗？还是他们使用其他系统？ 公开文档的最合适方法是什么？通过Web服务器/浏览器，还是通过大的（几个100MB）帮助文件？ 在编写代码文档时，您采用哪种方法？

13 documentation  documentation-generation  wiki