17

I'm interested in newer software/software stack to use in writing technical papers. For the longest time I have been use LaTeX to handle this but in looking at getting longer pieces published, such as books, other software is being used. The one that stands out the most so far is DocBook.

So the question is what software/stack of software is common for book authors of technical subjects using to write.

Edit: I primarily work on Mac. While using software in a VM isn't out of the question, unless there's not alternative it wouldn't be my first choice.

Edit: items indicated...

2
  • i'm looking at starting a book and i was leaning toward LaTeX
    – jrwren
    May 18, 2011 at 12:20
  • If you already know LaTeX, stick to it. The singular worst disadvantage of LaTeX is the steep learning curve. Once you're pas it, you have a tool at your hands others can envy.
    – SF.
    Aug 1, 2019 at 8:02

10 Answers 10

12

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.

1
  • I think the whole tool chain doesn't have to be easy. I'm okay with spending a little time building it out if needed. I think if I can easily produce structured content I can always come back and transform the content to another format with some clean up. PDF isn't my target output, like it was with LaTeX, since publishers will need to do at least some copy editing for the final format in question. Any "printable" output would only be for myself. Thanks for the responses, it provided more things to consider.
    – Travis
    May 17, 2011 at 16:37
6

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.

2
  • Thanks for your input Monica. It looks like Epic is totally overkill in it's current state. Some older versions appeared like they might be useful though. Oxygen I was also unfamiliar with and might be an option. I think it's time for to move beyond using vim now, there will be a lot of writing and having a more integrated experience might finally be worth it for me.
    – Travis
    May 17, 2011 at 17:05
  • @Travis, my copy of Epic is about six years old, so I'm not up to date on the newest features or bloat. :-) May 17, 2011 at 19:22
4

I would say that the newest, and in my view most promising, trend is 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).

2

Look into Lyx. This is a GUI front end that puts out document files in various formats expecially Latex. You can create a DocBook format document by exporting as SGML and then converting it.

See http://wiki.lyx.org/LyX/DocBook

3
  • It looks like the support is pretty broken for DocBook, from the link, "Currently it needs LyX 1.2.0 and it will not work with later versions of LyX." Additionally it links to a bug which has other bugs linked about this support. I don't think this would end up producing the output I want. However, I'll keep an eye on it, might be worth it if that gets cleaned up.
    – Travis
    May 18, 2011 at 16:23
  • LyX will let you use LaTeX in a much better environment. I'm not sure that DocBook is the end-all that you think. Still, I have a suggestion that I'll put as an answer.
    – Wayne
    May 19, 2011 at 1:48
  • I'm not sure DocBook is the end-all myself either. But working with publishers, it's the most commonly desired format for the type of technical books I am targeting. Thanks for your suggestions though.
    – Travis
    May 20, 2011 at 16:04
1

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.

0

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

2
  • I considered using Scrivener on my last proect. My deliverables were Word files, so the first thing I checked out was what a document looked like when transported into Word. And the answer was that there were no styles -- all the formatting was low-level. That might be OK if you're writing fiction or a magazine article. But for tech writing that's just unacceptable. A technical document has to be carefully structured so it can be maintained, and in Word styles are a crucial structuring resource. Sep 27, 2012 at 21:55
  • For DocBook support, see Scriv2DocBook. Looks like something that got invented so that Scrivener lovers could submit books to O'Reilly. You have to enter all XML by hand!! That's a deal-breaker for me. Sep 27, 2012 at 21:59
0

The best text editor for a text with formulas is definitely TeXmacs.

It has good rendering and powerful system of macroses.

TeXmacs is not a LaTeX editor but it has import and export for LaTeX format.

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.

0

FrameMaker is the go-to for books. Actual. Books. I would not want to produce a book-length technical project (even if the book will only be seen in digital form) without it. It has the necessary support for running headers/footers, TOCs, indexes, cross references, special characters, formulas, custom dictionaries, chapters, conditional text, and master pages.

I use HTML/CSS now for everything else. Millions of editors are available for HTML, while CSS provides the formatting flexibility of styles, and now with flexbox, grid, and so on, can do very complex layouts. All kinds of programs can import and export HTML, so you are not locked into any one program. You can be as structured or unstructured as you want. I use a free, WYSIWYG HTML editor (MS Expressions Web) to produce online help, user's guides, and in-program documentation.

And sometimes, you just have to use Word, because everybody has it, it's powerful, and you know how to use it. But it can suck (be unstable) for long projects like books of more than 100 pages.

-1

Another option is to rely purely on XML, validate against a schema, transform into HTML then apply different CSS sheets for different deliverables (i.e. web, print, mobile and embedded help).

2
  • 1
    While unquestionably a valid answer, owning everything involved here would consume a lot of time I wouldn't be interested in spending. There are likely some XSLTs and CSSs file to be pilfered to get part of way there though.
    – Travis
    Aug 8, 2011 at 16:08
  • You could use DITA or Docbook schemas, or another off-the-peg solution. As for CSS, it's fairly straightforward to learn, ad will stand you in good stead for any other web content you might work on (which could be a lot). Alternatively, a web designer or CSS-savvy friend might be very willing to help. Aug 8, 2011 at 20:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.