Questions tagged «documentation»

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

2
无处不在的语言-正确性和可用性之间的冲突
域驱动设计的核心部分是在整个系统中一致使用通用语言-在对话,代码,数据库模式,UI,测试等中。 我参与的一个项目已经有一个由国际标准组织定义的完善的领域语言。 但是,我们正在做的工作是针对公共网站的,该域的“正确”术语不一定代表公众通常如何使用和理解它们。 目前,我们正在使用的折衷方法是在所有地方都使用“官方”术语,但在接受标准(指的是UI组件,我们使用非正式名称)中除外。 这似乎是一种合理的方法吗?


5
代码文档:公共与非公共?
我就是那些思维定式的人,他们所写的代码应该是不言自明的,并且应该像书一样阅读。 但是,在开发供他人使用的库代码时,我尝试将尽可能多的文档放在头文件中;这就提出了一个问题:非公开的记录方法是否值得?他们不会直接使用它们,实际上,它们不能。同时,如果我分发原始代码(尽管很不情愿),那些非公共方法将是可见的,可能需要解释。 只是寻找您在旅途中看到或使用的一些标准和做法。

6
如果我不喜欢敏捷方法论,这会让我成为一个糟糕的程序员吗?[关闭]
很难说出这里的要求。这个问题是模棱两可,含糊,不完整,过于宽泛或夸张的,不能以目前的形式合理地回答。如需帮助澄清此问题以便可以重新打开, 请访问帮助中心。 8年前关闭。 我喜欢小迭代。我喜欢单元测试。我喜欢代码审查。我不喜欢的是很少或根本没有文档的开始。我一个人吗?我是否只是对该过程有误解? 任何想法将不胜感激。

5
最终用户文档示例的良好参考,并提供建议[关闭]
关闭。这个问题是题外话。它当前不接受答案。 想改善这个问题吗? 更新问题,以使它成为软件工程堆栈交换的主题。 6年前关闭。 我们的内部软件已被许多用户使用,培训部门要求我们提供最终用户文档格式的任何提示。 有谁知道在哪里可以找到培训部门用来启发灵感的软件最终用户文档的良好示例,或者在任何有很好建议的网站上? 这类似于此问题,但是我正在寻找供非技术用户使用的最终用户文档。

6
超链接的外部化源代码文档
已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗?更新问题,使其仅通过编辑此帖子来关注一个问题。 4年前关闭。 源代码为什么我们仍然嵌入自然语言描述(即,原因为何一行代码编写)的源代码中,而不是作为一个单独的文件? 鉴于为现代开发环境(高分辨率监视器,双监视器等)提供了广阔的房地产,IDE可以提供半锁式面板,其中源代码在视觉上与-而是与-内在链接其相应的注释。例如,开发人员可以使用超链接的标记语言(链接到其他软件要求)编写源代码注释,这将同时防止文档造成源代码混乱。 哪些缺点会抑制这种软件开发机制? 一个有助于澄清问题的模型: 当光标位于源代码中的特定行(上面以蓝色背景显示)时,与光标所在行相对应的文档将突出显示(即,与其他详细信息区分开)。正如问题中指出的那样,当光标在源代码中跳转时,文档将与源代码保持同步。热键可以在“文档模式”和“开发模式”之间切换。 潜在优势包括: 一次在屏幕上显示更多源代码和更多文档 能够独立于源代码编辑文档(无论语言如何?) 并行编写文档和源代码,而不会发生合并冲突 具有高级文本格式的实时超链接文档 准实时机器翻译成不同的自然语言 每行代码都可以清楚地链接到任务,业务需求等。 文档可能会在每行代码编写时自动加盖时间戳(指标) 动态包含架构图,解释关系的图像等。 单一来源的文档(例如,用于用户手册的标签代码段)。 注意: 文档窗口可以折叠 查看或比较源文件的工作流程不会受到影响 实施过程如何进行是一个细节。该文档可能是: 保存在源文件的末尾; 按约定(filename.c,filename.c.doc)分为两个文件;要么 完全由数据库驱动 通过超链接文档,我的意思是链接到外部源(例如StackOverflow或Wikipedia)和内部文档(即子域上的Wiki,可以交叉引用业务需求文档)和其他源文件(类似于JavaDocs)。 相关主题:业界对文档的厌恶是什么?

1
doxygen是否支持HTML输出模板?
我已经为记录了代码doxygen,但是我不希望它提供默认的HTML。我知道我可以通过提供自定义CSS,页眉,页脚等(如GNOME一样)以及如何向文件中添加通用PHP代码并将其保存为来对其进行自定义.php,但这并不是我真正想要的。 我想要的是像MSDN这样的输出。我真的无法形容。我的问题是,使用doxygen和模板之类的东西是否有可能,还是我必须输出XML并用另一个程序解析(我不介意编写)?

1
如何使用样本数据正确记录算法?
我想知道算法文档应包含什么?找不到合适的指导方针可以遵循。我想包括 算法总结 算法说明 流程图 伪代码 样本输入数据集(多个) 输出数据 单元测试 实验 客户要求提供这样的文档,以便:对我们自己的号码保持信心,并向潜在客户描述我们的流程,以便他们知道我们正在采取步骤来检查和验证我们的计算。 这样的文档看起来如何?(示例PDF) 您将在本文档中进一步包括什么? 我列举的是那么好,还是应该以不同的方式记录下来? 您将如何在Google中搜索此类文档样本?

5
存储与代码项目关联的文档的最佳方法是什么?
我们有很多与软件开发相关的文档。其中包括需求,设计文档,外部PDF,客户文件,测试说明等内容。目前,这些文档分散在各处(Wiki,“网络上的某个地方”,本地开发人员的硬盘(!),甚至更糟的地方)。 跟踪它们的最佳方法是什么?由于我们使用Visual Studio(2010)进行开发,并且该项目上实际上没有任何非开发人员,所以我认为将它们存储在VS“解决方案”中是一个好主意,这将使他们由源代码控制,并由所有开发人员普遍访问。 但是,VS似乎并不是专门为实现此目的而构建的。如果您编辑任何文档文件,即使使用构建属性“无”,“请勿复制”设置的文档文件,VS也必须先重建软件,然后才能再次运行。无法在解决方案中创建“文档项目”。(为此,我们使用一个空的C#项目)。Visual Studio和Word / Excel Flat不能很好地进行源代码控制。您无法查看签入的文件,然后决定进行更改,而无需先关闭文件,进入项目并在进行更改之前手动将其检出。充其量是缓慢而乏味的。 无论如何,这是我们团队能提供的最好的解决方案,但我真的希望我有一个更好的(免费)解决方案。

1
浮点函数的隐含精度
在回顾另一位程序员对某个函数的实现以计算正态分布CDF的实现时,我建议用Python的内置函数替换整个实现,或者使用通用的科学库SciPy。 另一位程序员指出,他们的文档中也math.erfc()没有scipy.stats.norm.cdf()提供任何精度保证。因此,在替换近似算法(该算法取自颇受好评的源,并记录了错误范围)时,我应该格外谨慎。 老实说,怀疑内置或库函数的准确性和精确度的想法从来没有想到。毕竟,多年来我一直在不停地调用诸如sin()和之类的函数,sqrt()为什么math.erf()还是scipy.stats.norm.cdf()应该有所不同呢? 但是现在,我很担心。我的问题是: 通常,如果文档中没有特别提及,是否暗示这些功能在IEEE双精度浮点提供的精度范围内完全精确到最后一位小数? 尤其是对于Python math.erf()或SciPy而言,这是真的scipy.stats.norm.cdf()吗?你怎么知道? 此手册页sin()说…… 当它们的参数接近pi的倍数或远离0.0时,这些函数可能会失去准确性。 当正弦函数是周期性且对称的时,为什么要存在这样的警告?似乎给调用者增加了规范输入以获取最佳准确性的负担。 另一方面,Mozilla的文档中Math.sin()没有提及准确性或精度。这是否意味着它是完全准确的,还是Math.sin()仅在某些情况下才像其他地方一样在JavaScript中才是准确的“常识” ?


1
如何使Javadocs中的代码示例保持最新
我正在开发一个小型库,该库提供基本的,众所周知的字符串指标的实现。主要是为了我自己的教育。因此,只要有空闲时间,开发就会发生。 因此,我已经完成了大多数流程的自动化工作,因此我可以不费吹灰之力就发布一个版本。但是,维护Java文档仍然是一个负担,因为它包含示例。 随着API的发展,我不得不一次又一次地手动检查每个示例。有一个更好的方法吗? 我已经考虑过将文档和示例移到一个单独的项目中(例如Caliper Tutorial),以便可以将其与常规代码一起重构和编译。但是,这确实使文档脱离了它所涉及的类。 嗯是的。我也想吃蛋糕。:D * <h2>Tokenization</h2> * * Tokenization cuts up a string into tokens e.g. * <code>chilperic ii son of childeric ii</code> is tokenized into * <code>[chilperic, ii, son, of, * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing * the individual tokens e.g. * …

4
我们应该寻找说谎的代码吗?
这是指答案中的讨论和对该问题的评论:业界对文档的厌恶是什么?。答案声称“代码不能撒谎”,因此应该是定位位置,而不是文档位置。一些评论指出“代码可能存在”。双方都有真相,至少部分是由于文档处理的差劲和不适当。 我们是否应该寻找说谎的代码,并将其与任何现有文档进行比较?还是通常它是所需要做的事情的最佳来源?如果它是敏捷代码,那么它说谎的可能性较小,还是该代码根本不说谎?

3
如何在文档中引用代码的特定区域?
我要离开一个项目,在我去之前,我的老板要我记录代码(我没有很好地记录文件)。这没什么大不了的,该项目并不复杂。但是我在我的文档中找到了一些要说的地方,“在XYZ行上通知某某某事”。 在这种情况下,引用特定的行号是没有意义的,因为添加或删除一行代码会立即使文档过期。是否有一些最佳实践来引用特定的代码行而不通过行号引用它? 我已经考虑过在代码中添加如下注释: /* linetag 38FECD4F */ 其中“ 38FECD4F”是该特定行的一些唯一标记。然后,我可以放入文档中,“在标记为'38FECD4F'的行上,注意这样的事情会发生。” 还有其他想法吗?我觉得通常最好记录整个代码单元,而不是记录它们的特定部分,但是在这个特定项目的情况下,会有大量的过程代码,这些代码从未被分解成较小的单元。

3
您如何在代码之外跟踪复杂的业务规则?
我有兴趣看看其他人是如何做到的。尤其是在多个不同的客户端使用具有稍微不同的业务规则的相同软件库的情况下。您使用哪种实践来记录一切应该如何工作或业务规则。 基本上,这样一来,当团队中有新开发人员时,便可以轻松地查看事物的工作原理,因为使某些东西没有错误和使某些东西正常工作之间显然存在区别。 拥有资源而不是每次遇到有关如何处理某事的问题时都必须让架构师或BSA参与对话,这真是太好了。

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.