Technical Documentation With Automated Publishing?

Ragetech asks: "I've been given the seemingly impossible task of finding a way to do automated publishing to the Web for primarily technical documentation. The task doesn't sound so bad, until you start looking the constraints and emphasize the need for a _inexpensive_ solution. I've looked at many different vendors but all of the ideal solutions seem to have price tags around $100k and above. They don't seem to be targeting small- or medium-sized businesses at all, and $100k is way outside my price range. So what are people using out there to do this type of thing? I want to enable our users to publish technical documents/manuals to the Web, preferably with some sort of structure (like, say, the DocBook DTD) so they can concentrate on creating/updating/keeping alive content. What do people use?"

"Here's the gist of what I'm looking for:

1. Complete solution, including a user-friendly, cross-platform editor, to some sort of content management, to automated publishing to the Web, and perhaps other formats such as PDF, RTF, etc.
2. If a mark-up technology, such as SGML/XML (which I would prefer) the way authors deal with content they cannot be burdened with learning a ton of markup. Ideally, they shouldn't have to learn much of anything... it should be a semi-WYSIWYG type editor such that the markup can be hidden from view and they can concentrate strictly on content and structure.
3. The authorship tool(s)/editor must be cross-platform, but the publishing engine and Web server could run on anything.
4. It shouldn't require a great deal of styling to get it to the Web. If I have to create a different style sheet for every darn document it isn't a good solution. It's technical documentation so it doesn't have to look too pretty, it just has to be structured sanely.
5. Preferably, it should be searchable on the Web.

I've looked at Arbortext, which has probably the best XML/SGML editor I've ever seen but they don't really have an integrated CMS/DMS (content management/documentation management system) and their web publisher is mucho bucks. I've looked at Crystal Software, Broadvision, etc. Everything comes in too high. My starting place was www.xmlsoftware.com but I can't find a whole, solid solution. For example, I setup Cocoon, a Java-based xml Web publishing engine from XML Apache.org but that still leaves me short an editor solution.

So here's the gist of my question: on one end of the scale, I could have users put technical documentation using Word. On the other end of the scale I could buy an integrated XML-based Web portal solution such as Data Channel. I need something in-between the lame and the awesome (but out of my price range). Any suggestions?? There have to be solutions out there, otherwise there's a whole untapped market I think."

what about conglomerate?

[burner]

I recently found conglomerate [conglomerate.org]. It looks like exactly what you want. It's probobly a little rough around the edges, but it's an open source project, so you've got the code if you want it. I've found that the site is a little iffy. Sometimes it's up sometimes it's down. It's in Brazil, I think.

Re:Check out Adobe FrameMaker...

[bestmick]

Does this product have some way to link the web application and database to the documentation? By this, I mean can it generate documentation from various kinds of source language inputs?

LaTeX

[embobo]

LaTeX converts to many fine formats such as postscript, plain text, and html. You cannot beat the quality of the output (at least the ps).

Though not an XML application, it is possible to parse.

LyX is a good wysiwg editor.

LyX2DocBook

[Matts]

I have a LyX2DocBook in the works, which would solve your editor issue, but I'd only give it to you if you consider AxKit rather than Cocoon :-) (I'm just kidding).

FWIW, all the AxKit documentation is DocBook, and converted on the fly to HTML, source and stylesheets available to download from the site (link in .sig).

Re:what about conglomerate?

[burner]

By the way, there are several good GUI XML editors . Check merlot [merlotxml.org] (open source java app), and alphaworks at ibm [ibm.com] for their GUI XML editor - not open source.

Re:Documentation language, then documentation GUI

[SamHill]

If you're looking for a quick "HOWTO" to getting LyX installed, there is one for RPM-based distros here..

For Debian, of course, just type apt-get update && apt-get install lyx.

learn markup

[Waltzing Matilda]

Learning and using markup will force users to concentrate on structure and content. Using a WYSIWYG or semi-WYSIWYG system will allow them to waste time on formatting matters. They will not consider structural elements if they cannot see them.

Before there were WYSIWYG editors, people had no problem learning to use markup.

If your content creators are really so stubborn as to refuse to learn to use a few tags, have them create the content first, and make their reviewer/editor put in the appropriate tags.

Just my thoughts.

Documentation language, then documentation GUI

[BitMan]

First off, don't put your documentation or data at risk, always use standard documentation languages. Languages that are not only open, not only formats taht will last for decades, but formats that are 100% facimile reproducable. Think like a publisher.

With that said, SGML with strict DTDs is key. Factor in the ubiquious nature of other, widespread documentation languages like TeX/LaTeX, HTML, XML and, now, DocBook and its obvious that you want to standardize on SGML and DocBook and convert between them all. Plus you need to be able to make PDFs quick and easy.

Now you need a GUI. The problem with most GUIs is that you are limited by them. Not LyX [lyx.org], it is highly-extensible and more and more features are added by the moment. Originally a WYSIWYG (actually WYSIWYM, "what you mean") for TeX/LaTeX, LyX can eat TeX/LaTeX, SGML and other mark-up in-line. Again, you have a GUI, but you are not limited by it.

From the GUI standpoint, LyX has automatic TOC, TOF, biblio, indices, notes and other table/figure generation. I personally love LyX for its margin note and sidebar features, as well as headers and footnote. Lastly, LyX can eat EPS in-line and the PostScript preview is exactly what PostScript will go to your printer (I hate apps with print previews that aren't exact).

Lastly, built in support for RCS/CVS revision control makes it an ideal application for multiple tech writers. IMHO, who need limited collaboration tools when you have real revision control underneath?

If you're looking for a quick "HOWTO" to getting LyX installed, there is one for RPM-based distros here. [leap-cf.org].

-- Bryan "TheBS" Smith

Check out Adobe FrameMaker...

[nellardo]

While it is a commercial, closed-source product, Adobe FrameMaker is rather good at this sort of thing - widely used by technical writers (e.g., it's one of the formats O'Reilly accepts manuscripts in). There's a version of it that produces SGML, FrameMaker+SGML, that comes with DocBook already configured.

It imports text in a variety of formats, including Word, so you can deal with free-lance writers. It is WYSIWYG, with options to view markup as well. Tables, graphics (imports there, too), and the best math formatting I've seen short of LyX/TeX - it will even evaluate mathematical expressions (Mathematica it ain't, but I don't know of any other non-emacsoid text editor/page layout program that can do matrix math and integrals)!

Automatic TOC, index and the like. Rock solid for simply huge documents, supports multi-file documents too. I've used it for an 800 page textbook, from original writing to "camera ready" output.

And the file format is exactly the same on Macintosh, WinDoze, and Unix. That's right - set up Samba, NetATalk, and NFS all pointing to the same directory, and any platform can edit the same documents (with its own cross-platform file locking, too).

N.B. I don't work for Adobe, nor have stock - I just happily use the product.