Workflow to Turn Wiki content into a system manual

Question

Hello,

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?

Thanks

Paul.

Answer 1

Most wikis support export via PDF e.g.:

• MediaWiki PDF Export
• DokuWiki PDF Export
• TWiki PDF Export

Answer 2

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.

Answer 3

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?

Answer 4

I followed Node's links and came across some mediawiki pages that I thought were noteworthy.

• Extension:OpenDocument Export
• Extension:PDF Writer
• Category:Data extraction extensions

Answer 5

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.

Answer 6

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).