为应用程序创建可维护的用户手册

Posted 2023-04-09

【中文标题】为应用程序创建可维护的用户手册

【英文标题】：Create a maintainable user manual for application

【发布时间】：2022-01-22 05:17:03

【问题描述】：

我正在尝试为内部（非公共）软件应用程序创建一个美观、易于维护的用户手册。

概括地说，这些是要求：

用户浏览的文档将是静态 html 页面。 文档需要能够从用户的硬盘上浏览。这些页面将不会在网络服务器上提供。或者换一种说法，用户硬盘上会有一个*** doc 目录，其中包含初始 index.html，然后是一个目录树结构，其中包含其余的内容。用户可以从自己的硬盘上双击 index.html 以开始使用，并且大多数（如果不是全部）其他内容（页面、图像、视频等）也在用户的设备。 网站的基本布局需要只是一个带有用户手册目录的左侧窗格，然后右侧包含部分内容。 我希望将原始内容放在易于维护的地方。我在考虑 Markdown，但如果有更好的建议，我愿意接受其他建议。不过，Markdown 看起来非常简单，因此它似乎是原始内容的一个很好的候选者。用户手册开发人员无需了解 HTML 或 CSS 即可添加内容。 一种。我们运行“something”来将原始内容的 HTML 生成为带有漂亮 CSS 的 HTML。

我觉得这样的东西已经存在，但我似乎没有想出正确的搜索关键字来找到它。

目前，我正在使用静态站点生成器，结果有些复杂。我还没有和他们中的很多人一起玩过——我偶然发现了 Hugo (https://gohugo.io/)，我一直在玩这个。当我进入雨果兔子洞时，我似乎有时会遇到方钉/圆孔问题。它似乎主要用于生成网络博客，这不是我的确切用例，所以我在让它从用户的设备上工作时遇到了一些困难。它似乎对原始内容的布局方式非常敏感，以提示它如何构建输出 HTML 树结构。我确信其中一部分只是我的学习曲线问题（我根本不是网络开发人员，所以所有对我来说都是新的），但有时感觉就像我花更多的时间试图了解 Hugo 为什么/如何渲染 HTML，而不是实际创建内容。

我还在网上看到了关于使用 Doxygen 生成用户手册的传言（尤其是 User manual with Doxygen），但我还没有找到任何关于如何真正实现它的好例子。我们已经在使用 Doxygen 来记录我们的代码，所以这可能是一个不错的解决方案，因为它只是减少了开发人员需要弄清楚的工具依赖/学习曲线。

任何人都找到了他们喜欢做类似事情的任何解决方案？

【问题讨论】：

doxygen手册本身就是借助doxygen编写的。问题是你有什么形式的用户手册输入文件。

目前我的输入文件是用 Markdown 编写的。如果需要，我可以很容易地将其转换为其他内容，因为每个内容页面都是 95% 的纯文本，只有少数 Markdown 标签（通常是指向图像、视频等的链接）

我应该补充一点，在我最初的帖子之前，我才刚刚开始研究使用 Doxygen，所以答案可能就在某个地方，但到目前为止我还没有偶然发现任何类型说明“如果您想使用 Doxygen 制作用户手册，这就是您的操作方法......”的操作文档/示例。我能找到的例子都与记录源代码有关。

Doxygen 可以很好地处理标准降价文件。您应该尝试一下，只需将您的降价文件作为输入提供给 doxygen。看看你喜欢/不喜欢什么。由于您对 doxygen 有一定的经验，因此创建 doxygen 设置文件应该不是什么大问题。顺便提一句。您使用的是哪个版本的 doxygen？

我绝对打算试一试 Doxygen（我目前有 1.9.1，但可以升级到 1.9.2）。我想我需要稍微重构一下现有的降价文件，然后才能尝试这样做，但我确实想看看这是否是一个合理的选择

【参考方案1】：

就在几天前，我发布了一个文档站点生成工具：https://luiinge.github.io/docsite-maven-plugin

它是用 Java 编写的，面向 Maven 项目，但即使您的项目是使用任何其他技术构建的，您也始终可以创建一个空的 Maven 项目，其中包含一个专注于文档的最小 pom.xml 文件。如果您有兴趣，我可以为您提供更多信息。

【讨论】：

这看起来很有希望！我对 Maven 了解不多，但我可以开始学习。我唯一关心的是添加 Java 和 Maven 依赖项（以及它们附带的任何学习曲线）。我们是一个小团队（只有 3 人），既要维护应用程序本身，又要使文档与我们所做的更改保持同步。所以我们希望这部分过程尽可能简单