Technical Documentation With Automated Publishing? 9
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:
- 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.
- 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.
- The authorship tool(s)/editor must be cross-platform, but the publishing engine and Web server could run on anything.
- 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.
- Preferably, it should be searchable on the Web.
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? (Score:1)
Re:Check out Adobe FrameMaker... (Score:1)
LaTeX (Score:2)
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 (Score:2)
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
Re:what about conglomerate? (Score:2)
Re:Documentation language, then documentation GUI (Score:2)
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 (Score:2)
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 (Score:3)
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... (Score:3)
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.