The people writing the user manual are not necessarily programmers, and they need a visual editor. A major issue is the internal format of the authoring tool; it should be readable text/html, so it's easy to compare versions of individual pages checked into version control.
views:
765answers:
10
+7
Q:
What is a good tool for writing a user manual (help file), which integrates with version control
Looks like a powerful tool! But I wonder what visual editor could be used to edit the source files. I don't think the writers of the user manual should have to edit xml code.
Ola Eldøy
2008-09-30 08:45:42
There is Epic Editor (http://www.ptc.com/products/arbortext-editor) but it's expensive and not very powerful.
Roel
2008-09-30 12:17:11
Xmlmind has a kind of visual editor. It's probably not WYSIWYG - but then again, in many cases, you *don't* want WYSIWYG anyway; you want What You Get Is What You Want.
Wilfred Springer
2010-02-13 22:17:22
A:
We are using APT. It integrates well with the CI (standard build artifact) and is more alive than for instance word document. It is also possible to generate PDFs and other formats when needed.
Petr Macek
2008-09-30 08:37:58
The drawback of this solution to me seems to be that you can not use a visual editor, and also that it is necessary to learn a new syntax.
Ola Eldøy
2008-09-30 08:43:02
+4
A:
Microsoft HTML Help Workshop can be used to create good quality professional CHM help files. All you need is a bunch of HTML files. The tool "compiles" all these and bundles into a single Help file. The HTML files can be generated using Microsoft Word/Frontpage or even Dreamweaver. You might want to consider source controlling these HTML files.
Nikhil Kashyap
2008-09-30 08:38:18
A:
I created a documentation system called Mandown (Markdown/Html/Javascript/file-based relatively linked documents for portability) which would easily go under version control. The visual editor part you would have to figure out separately - I sometimes use HTML-Kit which at least has a preview feature.
See:
http://stackoverflow.com/questions/99419/what-is-the-best-way-to-store-software-documentation#99600
Here's another tool to check out:
Xilize 3.0 http://xilize.sourceforge.net/
micahwittman
2008-09-30 08:43:37
Thanks for introducing me to WYSIWYM! Latex may be a bit too amitious for us, but WYMeditor for editing html files looks very interesting.
Ola Eldøy
2008-09-30 08:59:34
+1
A:
If you're using Visual Studio, take a look at SandCastle - http://www.codeplex.com/Sandcastle.
There's also a couple of tools that help you build sandcastle files, try searching "sandcastle" on codeplex. One of them is SandCastle Help File Builder (http://www.codeplex.com/SHFB), but I've never used it so I don't know if non-technical users will be happy with that.
StephaneT
2008-09-30 08:53:43
That's right, but you can also include arbitrary html. And the help file builder is more related to the question. But in retrospect, you are correct that this is not a complete solution to the problem.
StephaneT
2008-10-03 11:23:08
A:
There are other professional products which allow help file writing and they have support of "context ID" which makes context sensitive help possible. Doc To Help and RoboHelp are these type of products.
Hemant
2008-09-30 09:00:54
Are the internal (?) file formats of Doc To Help and RoboHelp readable text/html? If not, I believe it would be hard to compare different versions of a document from version control.
Ola Eldøy
2008-09-30 09:05:57
RoboHelp is a Microsoft Word plugin so the help files are in Micrsoft word format. When RoboHelp does a build it creates the HTML files from the Word documents. At least thats how it worked in a version from a few years ago.
jussij
2008-10-13 23:32:36
+3
A:
At my old job they used a tool by madcap software called flare.
It seemed to word really well.
Omar Kooheji
2008-09-30 09:21:34
+2
A:
You can use Subversion and MGTEK Help Producer. Help Producer makes help files from Word documents. TortoiseSVN comes with scripts to compare different revisions of Word documents, in Word itself (Word has a version compare tool).
Your users are going to want a visual diff tool that resembles the one they are editing in. If they are just slightly not-technical, DocBook or Latex aren't going to work (I've tried giving my users both, and I even tried Epic Editor as a DocBook editor which is very expensive but didn't work out very well after all). Sticking to something they know (Word) will prevent you many headaches.
I was very reluctant to go this route at first too, because I wanted a solution that was more 'technically perfect', but I realized over time that having happy and productive users was more important. Just saying that I know where you're coming from, but try the Word route - it works much better in practice than all the 'pure' text-based solutions that are out there. Regular users don't like markup based editing.
Roel
2008-09-30 09:24:14
Agreed; using Word as the editor is a huge selling point! Wishful thinking: What if... I could use html files as the 'true' source files, and Word as the editor, limiting the user to using only use the styles defined in our CSS... Wouldn't that be great?
Ola Eldøy
2008-09-30 09:38:48
Well you could set up styles in Word and have your users use that. Help Producer maps Word styles to CSS styles (you can define this mapping yourself). That way, the 'master formatter' has the power to change the CSS in a central location. Your users have to use styles to make this work.
Roel
2008-09-30 12:20:05
+1
A:
Mapcap Flare is the best commercial tool around. Written by the ex-developers of Robodoc
woany
2008-11-19 09:27:38