☰

如何提供IT工具文档？

tag-icon • tag-icon windows iis documentation
如何提供IT工具文档？

我想提供一个在 Windows 上使用的 IT 工具。它是 ISAPI Filter，我想描述安装、操作和配置。

目前，这是在一个文本文件中完成的，这个文件相当完整，但我认为它不太有用。我认为我很好地掌握了什么应该在文档中。我希望对如何部分。向 Windows Web 服务器管理员提供文档的最佳方式是什么？

.CHM？.PDF？.DOCX？.HTM？

编辑： 我有一个文本文件，但它变得非常长，并且链接、交叉引用、索引和组织功能有限。让我们看看，主要部分用等号下划线，小部分用破折号下划线……等等。所以我尝试以这种方式格式化它，但最终 .txt 文件无法缩放。

更新：我选择了 SHFB。以下是输出 HTML 帮助。您觉得怎么样？有用吗？

答案1

以下是我的看法：

  • ASCII 文本很棒 - 我可以在任何地方阅读
  • HTML 是第二好的 - 我几乎可以在任何地方阅读它
  • PDF 是可以接受的，但有点烦人，因为我可能需要在没有安装 PDF 阅读器的服务器上引用它
  • CHM 很麻烦，因为 HTML 帮助控件很蠢（多亏了 HTML 帮助控件的漏洞/弱点！），而且它不是一种非常友好的剪切/粘贴格式
  • DOCX 实在是太烦人了——我的服务器上没有安装“Office”，如果我需要参考那里的文档，我肯定不会加载它

答案2

我必须使用格式正确的 ASCII 文本文件。它们可以从笔记本电脑、服务器、Windows、Unix、Linux 等读取。

我不应该依赖 Web 浏览器、Adobe Reader、Office 或任何其他程序来了解如何在我的服务器上安装某些东西。它应该简单而轻松。

事实是……在紧要关头……如果有必要，我甚至可以通过手机阅读文本文件。

我相信任何在凌晨 3 点被困在托管设施且情况不太理想（例如从酒吧传呼、没有笔记本电脑等）的人都会同意这一点。;-)

仅我的一点意见...

答案3

你应该看看asciidoc。我用它做了一些简短的东西，输出非常清晰（当然，也是可定制的）。纯文本设计得非常易读，您可以轻松输出 docbook、HTML 和 PDF。使用任意数量的其他转换器，您也可以将其转换为其他格式，例如 CHM。

虽然这是一个非常通用的软件包，但是作为一个以 UNIX 为中心的软件包，我不知道它对 Windows 的支持如何。

答案4

我知道你已经接受了答案，但我想我会推荐狮身人面像。您在 reStructuredText 中编写文档，但可以轻松生成可搜索的 html（小型 javascript）。/

相关内容