将 Wiki 内容转变为系统手册的工作流程
我们正在向许多地方的许多用户（8 个国家/地区的 200 多个用户）部署新的软件系统。 过去我们为用户编写了一份手册，然后经常更新。 这工作正常，因为所有用户都有相同的手册，它涵盖了主要内容，但它也有问题，比如它不经常更新，我们有时会错过更新，并且一些用户会有旧副本。
我们一直在讨论在测试和部署阶段使用 wiki 来构建有关系统的知识库。 理想情况下，我们希望通过某种方式将其转换为某种形式的电子文档，然后我们可以将其“漂亮”并作为官方手册发送出去，并让用户使用和更新 wiki。
还有其他人做过类似的事情吗？ 对于 wiki 系统、工作流程、文档格式等有什么建议吗？
We're in the middle of deploying a new software system to lot's of users in lot's of places (200+ users over 8 countries). In the past we've written a manual for the users, then update it every so often. This works ok, in that all the users ahve the same manual and it covers the main things but it has it's problems, like it doesn't get updated that often, we sometimes miss updates, and some users will have old copies.
We've been talking about using a wiki during the testing and deployment phases to build a knowledge base about the system. Ideally we'd then like some way to convert that into some form fo electronic document that we can then 'pretty-fie' and send out as the official manual, as well as letting users use and update the wiki.
Has anyone else done anything similar ? Any suggestions for wiki systems, workflows, document formats etc?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（6）
大多数 wiki 支持通过 PDF 导出，例如：
Most wikis support export via PDF e.g.:
您可以编写一些东西，从 wiki 生成 LaTeX 并将手册呈现为 PDF。 使用像 hyperref 这样的包，您可以将交叉引用保留为超链接。
此外，您可以将来自多个来源（例如数据字典）的内容集成到 LaTeX 文档中，该文档可以与 wiki 内容混合和匹配。 您还可以设置架构，使其支持任意一种方式的交叉引用。
Framemaker 也可以使用生成的 MIF 文件，您也可以使用 Lout 以类似的方式或将您的 wiki 内容转换为 docbook，它允许您使用该格式可用的众多渲染选项中的任何一个。
顺便说一句，以下 Stackoverflow 帖子讨论了维护文档的各种系统。
用于生产的应用程序（不是标记语言）用户手册
LaTeX 可以用于生成软件附带的任何文档吗？
使用哪些工具来编写文档？
您的团队使用哪些工具来编写用户手册？
如何最好地编写文档（最好是乳胶）定位网络（html）和纸质（pdf）？
使用 DocBook 的最佳工具XML 文档？
用于格式化 XML DocBook 的推荐工具链是什么？
TeX/LaTeX 的继任者即将出现吗？
You can write something that generates LaTeX from the wiki and renders a manual to PDF. With packages like hyperref you can retain cross-references as hyperlinks.
Additionally, you can integrate content from multiple sources such as a data dictionary into the LaTeX document, which can be mixed and matched with the wiki content. You could also set the architecture up so it can support cross-referencing that goes either way.
Framemaker could also support this using generated MIF files, and you could also use Lout in a similar way or convert your wiki content to docbook, which would allow you to use any of the many rendering options available to that format.
As an aside, the following Stackoverflow postings discuss various systems for maintaining documentation.
Application (Not a Markup Language) for Producing a User Manual
Can LaTeX be used for producing any documentation that accompanies software?
What tools are used to write documentation?
What tools does your team use for writing user manuals?
How best to write documentation (ideally in latex) targeting both the web (html) and paper (pdf)?
Best tool(s) for working with DocBook XML documents?
What is the recommended toolchain for formatting XML DocBook?
Is a successor for TeX/LaTeX in sight?
Madcap Flare 是一个帮助和手动创作工具，它使用 HTML 作为每个项目的源代码话题。 您可以轻松地批量导入 Wiki 页面。 然后需要进行一些清理，但之后您就有了一个很好的单源系统，可以输出 CHM、可浏览网络的帮助、PDF、DOC/DOCX 等。
Madcap Flare is a help-and-manual authoring tool that uses HTML for the source of each topic. You could pretty easily do a mass import of the Wiki pages. Would then require some cleaning but after that you have a nice single-source system that can output CHM, web-browsable help, PDF, DOC/DOCX, etc.
您目前如何存储帮助源？ 是 MS Word 文件、MS 帮助还是 LaTeX？
如果您将帮助源文件置于版本控制之下，那么您将获得 wiki 的所有好处，而无需迁移到新系统 - 人们可以轻松地编辑帮助文件 - 可以跟踪、恢复这些更改等。像以前一样获取美化的手册。
How are you storing the help source at the moment? Is it MS Word files, MS help, LaTeX?
If you put your help source files under version control then you will get all the benefits of a wiki without having to migrate to a new system - people can make edits to the help files easily - those changes can be tracked, reverted etc. and you get the prettified manuals as before.
我跟踪 Node 的链接并发现了一些我认为值得注意的 mediawiki 页面。
I followed Node's links and came across some mediawiki pages that I thought were noteworthy.
我给出了之前的答案，这可能对“ wiki 到 PDF”部分——了解如何使用开源 PediaPress 代码或功能。 您也可以从中获得 ODF，尽管它们的 PDF 已经相当漂亮了（但我想您可能想为您的公司重新命名它并重新设计它）。
I gave a previous answer which may be useful for the "wiki to PDF" part -- look at using the open source PediaPress code or functionality. You can get ODFs from it too, although their PDFs are already quite pretty (but you might want to rebrand it and restyle it for your company I suppose).