Technical Writing Software

As Viktor said, FrameMaker is probably the best widely-used tool for doing what you're trying to do. Another (Windows-only) tool that I'm using now is Madcap Flare, but it's pretty pricy.

Other considerations:

DocBook is a spec, not a tool (as Viktor said). It is XML, so you can use any XML editor to write content. Possibilities include XML Notepad (free), XML Spy (used to be free, not now?), Oxygen ($), Epic ($$). (Personally I just use Emacs, but my coworkers think I'm weird. :-) )

To get from DocBook XML to usable output you'll need some transformation step. We use XSLTProc to generate HTML and XEP ($) to produce PDF. (The actual chain there is XML -> FO (formating objects) -> PDF.) We rolled our own build scripts for this, using style sheets and other resources downloaded from the DocBook site where we could. There might be better off-the-shelf support now (we build this about seven years ago), but since you mentioned being willing to roll your own, I wanted to note that it is doable.

posted almost 13 years ago

CC BY-SA 4.0

Monica Cellio‭ staff

2484 reputation 51 267 358 104

I would say that the newest, and in my view most promising, trend in in the use of lightweight markup languages, specifically Markdown, reStructuredText, and ASCIIDoc.

Both commercial WYSIWYG tools like FrameMaker and XML vocabularies like DocBook and DITA require complex and somewhat cumbersome editors and tend to clutter the writing experience with either formatting or structural conformance.

The lightweight languages, by contrast, can be written in the text editor of your choice with little overhead, and the source format is very readable, unlike XML. All three have well supported tool chains.

They don't have the capacity for structural constraints that you find in an XML application, but you did not indicate the need for that. For ease of writing a technical paper with reasonable support for things like math, using inexpensive or free tools, I would look at either reStructuredText or ASCIIDoc. (Markdown is more simplistic and more oriented to simple web pages.)

posted almost 8 years ago

CC BY-SA 4.0

Mark Baker‭

4351 reputation 12 1104 742 58

The answer depends a lot on what you have around you and what your needs are; assuming that

• You don't have extensive needs beyond Latin-1 and Math character sets, or simple use of Unicode character sets
• You don't have a need for overly-rich or complex page layouts (i.e. you're not doing page layouts that you'd see in a glossy magazine)
• You don't have external format/structure requirements that would conflict
• Your main operating environment is Windows

Then, Adobe FrameMaker is probably the best, first choice for long, technical documents.

Adobe has over the past few years orphaned pared off all the previous supported platforms for Frame (the 68K/PPC MacOS, brief flirtation with Linux, various Unices one at a time) to the point where it's not worth considering if you're not on Windows. (And sadly, historically speaking, I thought the branch of Frame they developed on Windows was not nearly as robust or as easy to use as the version of it on Mac, or Unix, but things may have improved now that they're really only supporting one platform for it.)

I have never used any tool that makes the writer's job as easy, end-to-end. There are better tools for page-layout, better tools for just the writing end of things, better tools for large scale, structured content-management, but if what you're trying to do is write a sizeable technical document, from scratch, and be able to produce reasonably flight-ready PDF you can pass to a publisher or print-house, then FrameMaker has been and still is pretty peerless.

DocBook is a specification for document structure more than it's a software stack, so writing with the DocBook structure would still require you to have a toolchain of some sort. The version of FrameMaker that supported structured editing did, I believe, support using the DocBook structure and let you produce SGML output instead of, or in addition to, "printable" output (i.e. PDF or PS). However, using Frame's structured features were, in my experience, significantly challenging and finicky: unless you have a firm requirement for fully structured source, or for passing DocBook to your publisher system, I'd question the need for it in your shoes.

posted almost 13 years ago

CC BY-SA 3.0

Viktor Haag‭

5 reputation 0 1 1 0

I use ClickHelp for technical writing. It is a browser-based documentation tool used to create online user manuals, knowledge bases, help files, FAQs, tutorials and publish them instantly in their portal. Otherwise, you can also export your writing in different formats.

There is no need to install anything.

This documentation tool has all the powerful features you may need for larger projects:

• Password-protected online help.
• Easy importing and exporting. The most popular formats like HTML, CHM, PDF, DOCX, DOC, RTF, EPUB, etc. are supported. So, if you want to move from another tool, you can import your documents and that’s all.
• Powerful Full-Text Search. ClickHelp has its own patented full-text search that helps you and your readers find topics easily, it also supports wildcard and also if you need, it’s possible to exclude specific topics from full-text search results.
• Reporting. ClickHelp has internal analytics that will help you measure team performance metrics and analyze end-user behavior statistics.

If you're interested, you can look through features here.

posted over 4 years ago

CC BY-SA 3.0

Kesi Parker‭

10 reputation 0 2 2 0

Check out Scrivener. I believe it can generate DocBook-format, though its true strength is in researching/creating a document, not editing formulas.

posted almost 13 years ago

CC BY-SA 3.0

Wayne‭

15 reputation 0 2 3 0

FrameMaker, while being the old industry standard, does not support right-to-left languages.

Madcap Flare has been touted for a years on the TECHWR-L forum as an alternative to FrameMaker. I have never used it, so I can't evaluate it.

Adobe InDesign is getting better at working in the same space as FrameMaker, but it's not there yet.

posted about 9 years ago

CC BY-SA 3.0

Voxwoman‭

5 reputation 0 1 1 0