编写基于 HTML 的用户手册的最佳软件 [关闭]

Posted 2023-04-09

【中文标题】编写基于 HTML 的用户手册的最佳软件 [关闭]

【英文标题】：Best software for writing HTML-based user manuals [closed]

【发布时间】：2011-04-17 23:27:32

【问题描述】：

我正在开展一个项目，我需要为一个软件生成最终用户文档。在明年的某个时候，我正在编写此文档的软件将被淘汰。因此，我不希望在专业级手册上花费大量时间。这是大学的研究生和一些内部专业人士会看到的。虽然如果它足够好和有用，我可能会将它作为免费文档反馈给开源社区。​​p>

我认为 html 手册会很合适。该软件是用 php 编写的，因此无论谁使用它，都将打开一个 Web 浏览器并准备就绪。这也导致我或其他人有可能将手册页面集成到软件本身中。

我对为这个软件制作/使用 wiki 不感兴趣。我真正想要的是一款可以像普通文档一样编写并生成简单 HTML 的软件。我知道有像 Dreamweaver 和 Frontpage 这样的软件，但我对旨在简化文档创建过程的软件特别感兴趣（其中截屏和视频的过程与简单的图像/视频编辑集成在一起）。

如果您认为另一种方法（HTML 文档除外）可能更好，我很想听听。如果您有其他方法，并且您认为您知道实现该目标的良好软件解决方案，请告诉我。

我对该方法和实现它的软件的主要愿望是

部署简单（HTML 页面不需要特殊设置。可以简单地部署一个包含所有手册页的帮助目录） 无需使用特殊软件（任何拥有网络浏览器的人都可以阅读 HTML） 便于我编写文档/学习曲线小（我不想花大量时间学习复杂的软件来处理相对较小的项目） 能够将文本、视频和图像组合到单个文档中（HTML 页面显然支持同时显示所有这些）

谢谢！

@Lie Ryan：“MediaWiki 将所有文本和数据（内容页面、用户详细信息、系统消息等）存储在数据库中......”这是我想要避免的。我认为 wiki 很棒而且很有用，但我只对以非常低的开销提供静态数据感兴趣。

【问题讨论】：

你有什么理由不想使用像 mediawiki 这样的东西吗？与 (X)HTML 不同，MediaWiki 具有轻量级语法（尽管我不得不说我更喜欢 markdown 语法），并且您不需要专业级的文档，而且我已经看到几个开源软件将其用于他们的文档.而且你肯定有一个支持 PHP 的服务器，因为应用程序本身是用 PHP 编写的。如果您不希望任何人都能够编辑文档，您可以简单地禁用匿名编辑和帐户创建。

【参考方案1】：

每当我需要编写用户手册时（即每次完成一个项目），我都喜欢使用Markdown。结合最少的CSS，非常好用。

Markdown 是文本到 HTML 的转换 网络作家的工具。降价允许 你用易于阅读的方式写作， 易于编写的纯文本格式，然后 将其转换为结构上有效的 XHTML （或 HTML）。

因此，“降价”是两件事：（1）a 纯文本格式语法； (2) 一个软件工具，用 Perl 编写，它 将纯文本格式转换为 HTML。

【讨论】：

这基本上正是我想要的 :) 谢谢！

【参考方案2】：

我想这并不能完全满足您的所有要求，但我是Sphinx 的忠实粉丝。您在ReST 中编写文档，并且可以非常轻松地生成 HTML 和 PDF 版本。 HTML 生成使用模板，因此可以自定义。此外，对于我们这些喜欢这些东西的人来说，拥有纯文本版本（ReST 在某种程度上是可读的）还有一个额外的好处:)

【讨论】：

Sphinx 链接不再起作用。

感谢@AliBigdeli...修复它。

【参考方案3】：

用 XML 编写手册，使用 docbook 之类的东西。这将使您可以对内容做任何您需要做的事情，然后以自己的方式生成演示文稿。

在 docbook to HTML 工具上有很多 tutorials。

编辑：我忘了提到OO can save in docbook。

【讨论】：

我喜欢 OO 支持像 DocBooks 这样的格式，但似乎支持还处于起步阶段。不过，感谢您的建议。

【参考方案4】：

我建议只在 OpenOffice 中编写并发布为 PDF。 PDF 甚至可能比 HTML 更重要，它与平台无关，并且在多个客户端和操作系统中看起来几乎相同。如果您真的想要视频，您可以链接到外部网站，例如 Youtube 或 PDF 中的 what-have-you。

【讨论】：

除非您正在为印刷书籍排版，否则您不需要关心页面是否偏离了 1 个像素或在某些其他操作系统中以不同的字体呈现。出于这个原因，我想说 HTML 比 PDF 更与平台无关。

@Lie Ryan：HTML 不支持嵌入字体，而且 CSS 在不同浏览器（尤其是旧浏览器）之间的解释存在很大差异。

但您不需要（也不应该需要）关心文本呈现的字体或颜色。基本上，您只需要文本可读并且可以显示图像和嵌入视频/声音和其他多媒体（flash、java applet 等）。

您可以通过 Webfonts 将字体嵌入到您的网站中。见en.wikipedia.org/wiki/Web_typography 和code.google.com/apis/webfonts

@bluebrother：CSS 字体下载支持非常有趣，我没听说过。无论如何，我同意字体不应该像清晰度那么重要。理想的解决方案类似于上面的 Sphinx 答案，可以发布为多种格式，包括 HTML 和 PDF。