15

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.

Ola Eldøy
  • 5,720
  • 7
  • 49
  • 82

11 Answers11

14

DocBook

alt text
(source: docbook.org)

Glorfindel
  • 21,988
  • 13
  • 81
  • 109
prakash
  • 58,901
  • 25
  • 93
  • 115
  • 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 Sep 30 '08 at 08:45
  • There is Epic Editor (http://www.ptc.com/products/arbortext-editor) but it's expensive and not very powerful. – Roel Sep 30 '08 at 12:17
  • 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 Feb 13 '10 at 22:17
  • DocBook completely separates structure from content, so the idea of a WYSIWYG editor just doesn't make any sense at all - it is a logical impossibility. I personally love DocBook, but I've found that many people just don't 'get' the idea of creating structured documents - they can think only in visual terms. These people generally loathe using DocBook and make a complete mess of the structure because they are trying to make something that 'looks right' on the page. – Ian Goldby Jul 14 '11 at 11:55
  • 1
    @Ian Goldy I dont agree I used Docbook for a project because I liked the way you specified the structure but it was very difficult to write the text directly in the xml document, it wasnt until the final html was generated that I could see the mistakes I'd made. I see no reason why you can't have a WYSIWYG editor that saved the doc as a docbook xml file because most docbook elements have a synomous elemt in a WYSIWYG editor ie -> . Docbook doesnt separate structure from content, both in the same document,what it does is separate structure from how structure is realised. – Paul Taylor Aug 12 '12 at 23:34
  • @Paul: I use the XMLMind XML Editor for writing DocBook content, so I get to see the text itself, without XML tags cluttering up the display. But it *is* important to remember that it is not a WYSIWYG editor. Something that is rendered as bold in the editor might be italics in the final realisation. XMLMind XML Editor has a status bar that tells you what the current XML element is. Without that you would often be lost - because there is no one-to-one mapping between something on the screen and an element in the XML markup. – Ian Goldby Aug 13 '12 at 07:09
6

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
  • 1,049
  • 2
  • 11
  • 15
6

Latex. Lyx provides WYSIWYM for writing latex files.

grom
  • 15,842
  • 19
  • 64
  • 67
4

At my old job they used a tool by madcap software called flare.

It seemed to work really well.

Ben
  • 54,723
  • 49
  • 178
  • 224
Omar Kooheji
  • 54,530
  • 68
  • 182
  • 238
3

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
  • 19,486
  • 24
  • 91
  • 127
  • 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 Sep 30 '08 at 09:05
  • 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 Oct 13 '08 at 23:32
  • We're sticking with an older version of RoboHelp. The files are standard html fare, so works well with version control. – Ola Eldøy Jul 04 '12 at 08:20
3

A good combination to consider is Subversion, DocBook and Publican.

At the moment, this is one of the toolchains in use by the world's largest provider of open source solutions, and the name behind much of the world's use of Linux-based operation systems in the enterprise market. Most (and close to all) of Red Hat's official documentation is created in such a manner. Same goes for Fedora.

The major "pro" here is that these are freely available tools, with a strong overlap in the market of technical writers. All of which will be able to (but might not want to) write in XML, and picking up DocBook is like picking up HTML in the 90's. Subversion is a very common version control tool, that like DocBook is relatively easy to implement and use. Publican is a great publishing tool that can take DocBook XML, and publish it to PDF, HTML, HTML-single, etc. Obviously your writers can use a WYSIWYG like Serna, but I use snippets in Geany (on Fedora) or TextMate (on OS X) personally.

The major "con" is the perception of technicality. Your writers might want WYSIWYG (and can have it), and depending on your documentation needs, this might be what you end up using. As you would know, there's a market out there for "Technical Writers" who specialize in fixing Microsoft Word styles (and markup), so the arguments for separating "authoring" from "publishing" are based on proven but distinct use cases for organizations that require documentation to be held up to the same standards of the engineering/programming/source production.

Some of the extreme advice you will get comes from people and companies that have been exposed to the value of XML documentation, and especially those in the realms of DITA, where certain multi-nationals have a reputation for acquisitions that are influenced by the format and availability of the product knowledge. there are also the arguments that locking your documentation into a "sticky" or closed format doesn't help the future maintenance requirements. This is where the open source options gain support on a corporate level. Plus, obviously, it's free.

davidryan
  • 2,222
  • 20
  • 31
2

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
  • 19,338
  • 6
  • 61
  • 90
  • 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 Sep 30 '08 at 09:38
  • 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 Sep 30 '08 at 12:20
  • +1 didn't know TortoiseSVN integrates with Word, thx – ykaganovich Oct 01 '08 at 23:11
1

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 What is the best way to store software documentation?

Here's another tool to check out: Xilize

Community
  • 1
  • 1
micahwittman
  • 12,356
  • 2
  • 32
  • 37
1

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.

stombeur
  • 2,704
  • 22
  • 45
  • Sandcastle is for documenting class libraries, not creating user manuals. – Joe Sep 30 '08 at 09:29
  • 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. – stombeur Oct 03 '08 at 11:23
1

Mapcap Flare is the best commercial tool around. Written by the ex-developers of Robodoc

woany
  • 1,219
  • 2
  • 11
  • 10
0

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
  • 1,493
  • 1
  • 15
  • 19
  • 1
    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 Sep 30 '08 at 08:43