问题标签 [documentation]

我创建了一个应用程序，需要在下个月“移交”给支持小组。

该应用程序相当小（开发 2 个月），由两个客户端应用程序和一个数据库组成，它是用 c# 为 windows 平台编写的。

我对支持文档中包含的内容有一个广泛的想法，但到目前为止，在我的职业生涯中，我不需要制作很多支持文档，我希望包含一个可靠的项目列表。

我想我的目标是让支持小组中的每个人的生活更轻松，并尽可能无压力。

所以我想我的问题是：

1. 支持文件绝对应该包含什么

2. 您在支持文档中添加了哪些其他内容以使它们更加有用。

3. 在移交之前可以进行哪些其他活动以使我们的生活更轻松？

我需要开始弄乱一个 vb.net(vs2008) 项目文件，并且我想要一个参考，理想情况下，它是规范。

任何链接都会非常有帮助

我需要在我的 perl 文档中使用 utf-8 字符。如果我使用：

我看到奇怪的字符。如果我使用：

一切安好。

我使用 Ubuntu/Debian。

是否有关于在 Pod 中使用特殊字符的 HowTo？

这是一个使用德语变音符号“Just a Test: äöüßÄÖ”的小例子：

我有一位同事坚持认为他的代码不需要注释，这是“自我记录”。

我查看了他的代码，虽然它比我看到其他人编写的代码更清晰，但我仍然不同意自文档代码与注释和文档代码一样完整和有用。

帮助我理解他的观点。

• 什么是自记录代码
• 它真的可以取代注释良好和记录良好的代码吗
• 是否存在比有据可查和注释的代码更好的情况
• 有没有代码不可能在没有注释的情况下自我记录的例子

也许这只是我自己的局限性，但我不明白它如何成为一个好的做法。

这并不是要成为一个论点 - 请不要提出为什么注释良好和记录良好的代码是高优先级的原因 - 有很多资源表明这一点，但它们并不能说服我的同行。我相信我需要更充分地理解他的观点才能说服他。如果必须，请提出一个新问题，但不要在这里争论。

另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点（即积极的方面）。

我需要采取哪些步骤才能通过 Visual Studio 中的构建步骤自动构建 HTML 文档？我有所有的评论和正在生成的 comments.xml 文件，并安装了 Sandcastle。我只需要知道要在构建后步骤中添加什么来生成文档。

为了工作，我必须使用外部公司的 API 编写代码来处理他们专有的数据库解决方案。不幸的是，他们提供的文档更多的是一个示例指南，而不是正确的 API 文档，因此它对错误代码、方法返回和异常等细节非常简单。

例如，一个类将有一个 .GetErrorCode() 方法，但我不知道这些错误编号是什么意思，因为它们没有记录哪个编号与哪个错误匹配。在许多情况下，一个方法将返回一个 Object，但没有文档说明它实际返回的 Object 类型。我一再要求他们提供适当的文件，但他们似乎认为上述细节是保密的。那么，是否有任何工具或方法可以解决我有限或在某些情况下不存在的文档。

请注意，我正在使用 Visual Studo 2005 并在 .Net 下使用 C# 进行编码。

在任何人回答“不要使用 API”之前，我必须这样做，这是为了工作。

我正在尝试查找我可以设置的所有可能选项web.config。令人惊讶的是，我根本找不到这个。我预计它会在MSDN中的某个地方。

我知道我可以在技术上添加“任何东西” web.config，我正在寻找的是 .NET Framework“交付”使用的东西。

特别是，现在我对该<mailsettings>部分感兴趣。
例如，在我发现的许多示例中，我注意到它们设置了DeliveryMethod="Network". 我真的很好奇这个属性可以取什么其他值。

是否有关于所有属性及其所有值以及它们的所有影响的文档？

我不确定这里的最佳实践是什么，但我经常看到缩写的变量名，尤其是在范围很小的时候。所以（使用简单的 Ruby 示例）而不是def add_location(name, coordinates)，我看到类似的东西def add_loc(name, coord)——我什至可能看到类似的东西def add_loc(n, x, y)。我想当一个人习惯于看到缩写时，较长的名字可能会让他们感到厌烦。

冗长是否有助于可读性，还是只会伤害每个人的眼睛？——人们更喜欢缩写和缩短的名字而不是更长的名字吗？

我需要将我刚刚发布的更新公司网站的内容移交给我们的内容编辑。显然，带笔记的培训课程是不够的。很公平。

因此，更可怕的文档迫在眉睫。在对 Google 进行了相当简短的搜索后，我找不到任何相关且可用的模板来用作网站或 Web 应用程序移交的基础。我发现应该出现在此类文档中的最有用的项目列表是专家交流（敌人）：

1. 系统概述、概述
2. 流程和跨部门流程
3. 系统配置、设置和依赖项
4. 技术要求、特点和限制
5. 支持过程
6. 用于故障排除的相关方的升级列表和联系信息

这是一个很好的工作基础——我可以为那些只会对网站进行内容更改的用户“简化”，但有人知道云中可用的良好标准模板吗？是否应该将更多内容添加到此列表中？

我有一个用 C++ 编写的 COM SDK，我想为我的产品创建文档。我知道大多数人可能不会使用 C++ 与这个 COM 组件集成，但很多人会。

哪种方法最适合描述 API，而不会丢失 C++ 开发人员需要知道的细节。