Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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...

share|improve this question
    
i'm looking at starting a book and i was leaning toward LaTeX –  jrwren May 18 '11 at 12:20

7 Answers 7

up vote 9 down vote accepted

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.

share|improve this answer
    
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 '11 at 16:37

As Viktor said, FrameMaker is probbly the best widely-used tool for doing what you're trying to do. 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 cowkrers 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.

share|improve this answer
    
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 '11 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. :-) –  Monica Cellio May 17 '11 at 19:22

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

share|improve this answer
    
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 '11 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 '11 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 '11 at 16:04

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

share|improve this answer
    
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. –  Isaac Rabinovitch Sep 27 '12 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. –  Isaac Rabinovitch Sep 27 '12 at 21:59

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.

share|improve this answer

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).

share|improve this answer
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 '11 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. –  Jimmy Breck-McKye Aug 8 '11 at 20:54

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.
http://writers.stackexchange.com/questions/2845/technical-writing-software?answertab=oldest
writers.stackexchange.com
crawl=CC-MAIN-2015-18
107399
application/http; msgtype=response
sha1:DJ5DK2PSVIYT3OIGULOVKACPQX72DJAL
<urn:uuid:583f6e21-62e6-4965-9443-2cb171da16de>
2015-04-25T01:56:34Z
104.16.12.13
sha1:5NKJPIWHNCAHSAK5HD6OKKRZIUKMRAZS
<urn:uuid:d5e69159-ae31-40e2-b645-78b48165cd52>
http://writers.stackexchange.com/questions/2845/technical-writing-software?answertab=oldest
length
response
<urn:uuid:ebc49bde-44f9-4f2d-9b46-2ea0e9b55b32>
robots: classic
hostname: ip-10-235-10-82.ec2.internal
software: Nutch 1.6 (CC)/CC WarcExport 1.0
isPartOf: CC-MAIN-2015-18
operator: CommonCrawl Admin
description: Wide crawl of the web for April 2015
publisher: CommonCrawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf