Questions tagged «documentation»

W3Schools的声誉是不完整的，有时是错误的，并且被广告所困扰。尽管如此，当在回答SO问题时查找某些内容或链接到文档时，它仍然是唯一方便的跨浏览器资源。 还有其他资源，例如Mozilla开发人员网络正在做越来越出色的JavaScript记录工作，以及传奇而出色的Quirksmode。但是，尽管它们如此出色，但它们仅涵盖了我所谈论的部分领域，并且没有提供社区编辑和质量控制选项。 是否有人意识到创建协作编辑的跨浏览器HTML / CSS / JavaScript / DOM百科全书的努力？如果可以的话，我想像W3Schools的挑战者那样，像是Experts Exchange那样的挑战者。

12 web-development  documentation  html  css 

我们正在寻找整个产品线的文档更新。的那部分包括参考手册用于编程语言用作系统的一部分。 在编写用于编程语言的参考手册时，为使该语言的新手拥有最大的可用性，最好的构造方法是什么？ 记录每个关键字的关键方面是什么？ 句法 描述 参数-如果适用 返回值-如果适用 用法示例？ 还有其他我想念的吗？ 概念（例如锁定策略，与性能相关的详细信息）是否也应在本参考手册中进行记录，或者是单独的文档？ 这是供外部消费。我们已经有完整的文档集（请参阅：http : //www.rocketsoftware.com/u2/resources/technical-resources）。制定出我们应该做的事情与众不同-我已经有了我的想法，但是和往常一样，我尽量不要仅仅依靠我的观点。 受众：技术开发人员使用我们的数据库和工具来跨许多行业生产软件。

12 programming-languages  documentation 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 6年前关闭。 对于一个项目，我需要使用一些旧游戏和相关软件中的各种文件类型-配置文件，保存，资源档案等。这些文件的大部分尚未记录，也没有与之配合使用的工具，因此我必须对这些格式进行反向工程并构建自己的库来处理它们。 尽管我认为大多数需求不大，但我打算发表自己的努力成果。是否有记录文件格式的公认标准？环顾四周，有几种正在使用的样式：有些样式（如.ZIP文件格式规范）非常罗;；有些样式则非常冗长。其他的，例如XentaxWiki上的，则更为简洁-我发现其中一些难以阅读；我个人最喜欢的是对PlayStation 2存储卡文件系统的描述，其中包括详细的描述性文字和一些带偏移量的“内存映射”等，它也与我的用例最匹配。对于不同的格式，它会有所不同，但是似乎应该有一些我应该遵循的一般原则。 编辑：我似乎没有很好地解释我想做什么。让我构造一个例子。 我可能有一些旧软件，将其配置存储在一个“二进制”文件中-一系列位域，整数，字符串以及所有这些东西被粘在一起并被程序理解，但不是人类可读的。我破译了。我希望以一种人类可读的方式准确记录该文件的格式，作为实现库以解析和修改此文件的规范。此外，我希望其他人可以轻松理解这一点。 可以使用多种方法来编写此类文档。上面的PKZIP示例非常冗长，主要以自由文本形式描述文件格式。PS2示例提供了值类型，偏移量和大小的表，并对它们的含义进行了广泛注释。许多其他变量（例如XentaxWiki上的变量）仅列出变量类型和大小，几乎没有注释。 我问是否有类似于编码样式指南的标准，该指南提供了有关如何编写此类文档的指南。如果没有，那么有没有我应该效仿的著名例子？如果不是，那么至少有人可以总结一些有用的建议吗？

12 documentation  reverse-engineering 

我想知道记录业务规则的正式和最常用的方法是什么？还有如何记录开发工件的UI规范（例如，记录表单字段以及按钮在表单，信息文本上的行为方式等）

12 documentation  business-rules 

我目前正在为我的“软件开发”研究而毕业，在该研究中，我必须在外部公司中单独开发复杂的软件。所有这些都需要以结构化的方式完成，创建所有相应的文档。 对于这个项目，我选择使用IEEE标准文档：软件需求文档（SRS），软件体系结构文档（SAD）和软件设计文档（SDD）。尽管在学校另有授课，但对于该项目，我选择在开发后（而不是之前）创建SDD 。我的理由是： 我从事实习的公司给了我指导，以实验方式创建满足某些要求的复杂软件。由于他们在项目定义中给了我很大的自由度，因此几乎没有什么可以事先确定的，并且在开发过程中进行试验时最好能遇到。此外，我以个人方式创建软件，对于公司中的其他任何人来说，事先进行此软件设计对我来说都是没有好处的。事前做会花很多时间，以后再做，因为我可以确定由于项目的不确定性，我做的设计必须作很多改动。这对我来说适得其反。 在开发后创建SDD是否有充分的理由？如果没有，那有什么正当理由吗？ 编辑：之后创建SDD的原因是为了将来的开发人员继续该项目。在毕业期间，我将无法完成整个项目，因此其他开发人员将不得不继续使用当前的代码库。

11 design  documentation  software  iso 

关闭。这个问题是题外话。它当前不接受答案。 想改善这个问题吗？ 更新问题，以使它成为软件工程堆栈交换的主题。 6年前关闭。 我主张对源代码进行评论并记录软件产品。根据我的个人经验和观察，在必须开发软件或维护软件的过程中，对经过严格注释的源代码进行的工作以不同的方式帮助了我。 但是，还有一个阵营说评论最终毫无价值，或者其价值值得怀疑。许多不加评论的编码支持者认为： 如果一段代码写得很好，那是自我解释，因此不需要注释 如果一段代码不是不言自明的，则对其进行重构并使其变得不言自明，以便它不需要任何注释 您的测试套件就是您的实时文档 随着时间的流逝，代码和注释不同步，这成为令人头疼的另一个原因 敏捷表示工作代码比大量文档更重要，因此我们可以放心地忽略编写注释 对我来说，这只是教条。再次，我个人的观察是，由才华横溢，经验丰富的开发人员团队编写的软件最终最终会产生大量不言自明的代码。 同样，Java API，Cocoa API，Android API等表明，如果您要编写和维护高质量的文档，则可以实现。 综上所述，基于个人信念的有关文档优缺点的讨论以及对源代码的评论通常不会以良好的结局而无法得出令人满意的结论。 因此，我正在寻找有关软件文档（尤其是注释源代码）对其质量和可维护性及其对团队生产力的影响的影响的学术论文和实证研究。 您是否偶然发现了此类文章？如果有的话，结果如何？

11 productivity  documentation  code-quality  maintainability  engineering 

是否有用于注释正则表达式的通用方法：内联注释引用RegEx的不同部分或针对所有表达式的常规注释？

11 documentation  coding-style  comments 

我有一个大学项目，我不会马上开始，但是已经考虑了很长时间。我了解大学的项目开发与行业不一样（我目前是实习生），所以我现在要指出的情况对于实际的软件开发人员而言似乎有些荒谬。^^' 该项目本身要求我们记录很多工作。因此，除了交付涉及某些标记的代码外，我们还必须交付文档，包括： 需求分析文件 项目计划 用例，对象和动态模型以及验收测试的计划清单 测试过程的文档以及测试的成功程度 其他一些时间使用的讨论和分析，等等。 这些可交付成果将以以下方式交付： RAD第一 随后是项目计划，用例，模型和测试（大约3周后） 最后，是实际程序的文档，测试过程等。+实际程序本身（大约5周后） 因此，据我了解，这实际上是针对该项目的瀑布式方法。唯一的问题（在我看来）是这是一个大学项目，在项目周的学期末，学生已经有足够的压力来尝试开发项目。我真的不想在学期末对所有内容进行编码/开发/测试，那时我将要面对的其他评估工作都令人感到恐慌。 我至少想尝试执行某种迭代的开发周期，这意味着我们可以及早开始编码/原型设计，拥有一个连续的开发周期，而该周期并不专注于在最后一刻做所有事情，也没有太多压力学期末完成这个项目。现在是我的实际问题： 我可以以某种方式调和必须以快速，迭代/原型开发周期提供所有这些文档吗？ 是否有策略以迭代方式生成文档？ 我问这个问题并期望它在大学中可行是完全不合理的吗？ 另外，我知道这个问题是非常本地化的，所以我想问一下我在行业方面问过的同样的问题，以及每个团队敏捷过程面临的许多此类问题是否有所不同或公司。 无论如何，对这有多长时间感到抱歉，如果您已经读完了所有内容，谢谢！如果您能抽出宝贵的时间来回答，我将不胜感激！谢谢！

11 documentation  iterative-development 

有时候，有1％的代码需要足够的计算强度，因此需要最重的底层优化。通常，示例是视频处理，图像处理和各种信号处理。 我们的目标是记录文档并教授优化技术，以使代码不会变得难以维护，并易于被新的开发人员删除。（*） （*）尽管在某些不可预见的未来CPU中特定优化可能完全没有用，所以无论如何都会删除代码。 考虑到软件产品（商业或开放源代码）通过拥有最快的代码并利用最新的CPU架构来保持竞争优势，软件作者通常需要调整其代码以使其运行得更快，同时为特定产品获得相同的输出。任务，允许少量舍入错误。 通常，软件编写者可以保留函数的多个版本，作为每次进行的优化/算法重写的文档。一个人如何使这些版本可供其他人学习其优化技术？ 有关： 干净可读的代码与快速难以读取的代码。什么时候越界？

11 documentation  code-reviews  optimization 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 4年前关闭。 我已经完成了一个Web应用程序，该应用程序基本上是用PHP开发的，它只是另一个常规的Web应用程序。通常，当我交付最终产品版本时，我只是将代码文档和体系结构信息移交给客户端。但是，对于这个特定项目，客户坚持要拥有有关该项目的完整的输入和输出数据。 所以我只是想知道...除了代码和体系结构文档之外，我还可以为客户提供哪些强制性技术文档和非技术文档？ （也可以向客户介绍有关该项目的各种统计数据和数据，这样他才能真正知道所涉及的工作量以及产品的实际效果如何。）

11 project-management  documentation  documentation-generation  projects-and-solutions 

我想通过研究著名的开源项目来提高自己的编程技能，但是我发现仅跳入其源代码很容易迷路。 因此，我决定阅读有关其设计或体系结构的文档（例如UML图），以便首先了解其代码的组织结构。但是，令我惊讶的是，我找不到大型的开源项目（例如Hibernate，Spring，ASP.NET MVC，Rails等）的任何体系结构文档。 因此，我开始怀疑：如果新来的开发人员没有要阅读的体系结构/设计文档，或者项目经理只是打开源代码但关闭了文档，那么开源项目如何成功？

11 open-source  documentation  asp.net-mvc 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 5年前关闭。 最近，我一直在阅读有关软件项目的一些建议，但我对所看到的内容有些担心。我经常觉得提案很仓促和/或考虑不周。 提案很有可能不需要像一篮子水果，但是如果您要投身工作或寻求资金支持，则必须有一些准则来构成“体面的”提案。 我想知道是否有人知道编写软件建议的良好指导方针，或者是否可以将我指向书籍/网站等？

11 documentation 

已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗？更新问题，以便通过编辑此帖子以事实和引用的形式回答。 2年前关闭。 有没有人尝试过在实际编写代码之前先创建完整的代码文档？我早些时候就在考虑这个问题，因为我认为这将有助于编写具体的接口，并通过让您考虑类的交互方式来确保您的初始设计不会落空。这是一个好主意吗？有人尝试过吗？厄尔

11 documentation 

经过大量搜索，我未能回答与软件开发领域中已知的假设有关的基本问题： 什么是已知的： 对足够的代码文档（无论是Doxygen标记，Javadoc还是仅仅是大量注释）实施严格的政策，都会增加开发代码所需的时间。 但： 拥有详尽的文档（甚至API），可以在新手和经验丰富的开发人员添加功能或修复bug时带来生产率的提高（有人认为）。 问题： 保证此类文档所需的额外开发时间是否能被下游生产率的提高（从严格的经济意义上来说）所抵消？ 我正在寻找案例研究或答案，可以带给他们客观的证据来支持得出的结论。 提前致谢！

11 java  c#  c++  documentation  coding-standards 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 4年前关闭。 我一直想知道您如何找到未公开/专用的 API？ 例如Apple未公开的/私有的API，Play Station，Windows Phone 7，Win32内核，Windows API，隐藏的回调等... 黑客使用哪些工具来查找私有和未记录的功能？ 在哪里可以读到人们深入研究私有API和反向工程技术的经验，这些经验揭示了API文档中通常解释的秘密？ 谢谢， 阿

11 programming-languages  learning  documentation  api