Slashdot Mirror
Tools & Surprises For a Tech Book Author?
Fubari writes "I have questions for those of you who have written books: what writing tools have you found helpful? I want to start my book off right (so I'm pretty sure I don't want to write it in MS Word). What has and has not worked well for you? So far I have thought of needs like chapter/section management, easy references to figures (charts, diagrams, source code), version control (check in/check out parts like chapters, figures, etc.), and index generation. I would also welcome advice about what I don't know enough to ask about. Did you encounter any surprises that you wish you had known about back when you started out?"
Check out the O'Reilly website:
http://oreilly.com/oreilly/author/ch02.html#tools
If you have a publisher already lined up, ask them what they want. Most publishers already have copy editing / print production processes in place, and are very specific about what they want from authors (e.g. what formats for images and graphics, templates for your chapters (often Word), and a style guide for writing, how figures should be referenced, etc. You can then use whatever tools you want, provided they deliver what the publisher wants.
If you don't have a publisher lined up, try and keep your materials in generic and easy-to-changes formats, so you can pour them into whatever format your publisher wants.
Remember, production is all about the publisher - it is not about you.
If you are self publishing, there are lots of web-based self-publishing companies - and they too describe what you need to feed them.
I'd have to say that there were a few surprises I learned along the way :)
First, expect it to be another full-time job. It takes up as much time as you have, and even more, and forget about having a personal life while you're writing it. The people I know who've done the best job writing a tech book are those who are independent consultants who have non-billable time or employees where their employer supports their writing a book. The extra time each of those kind of people can get to write during working hours is a huge help.
As far as using Word goes, it works well enough for this stuff. Expect to use a separate file for each chapter. I used a subversion repository to check everything into and out of, just to be safe.
Make writing a habit. Set a production schedule and stick to it -- its too easy to take a day off, which then turns into two days, into a week, and then just gets worse and worse. Set out a plan, both long term and short term, track your progress, update the plan as you go, and keep writing.
Finally, using a continuing example throughout the book might be nice for readers, to give them a continuing context, but it greatly increases the risk of a lot of rework on your part if you change your mind about something halfway through writing. You'll have to go back and re-edit everything that depends on the decision you changed. It does make it nice for the reader but much harder for you.
Good luck! Its a great learning experience, whether you finish the book or not.
-- bab
It sounds like you want LaTeX. It has a built in reference, chapter, figure/table referencing and an ToC system. It is great for equations and a whole host of other things. It does have a learning curve, but it works great. The one problem with it is that it does not have a spell checker. So what you do is type in Word and then copy/paste it into LaTeX for the formating and everything else.
Fly me to the moon Let me sing among those stars Let me see what spring is like On jupiter and mars
Save often!
And wise enough to know when to ask for help, something too few tech people know how to do...
I started writing books (novels and textbooks) when all I had was a typewriter. Since then using XyWrite and now Word, I've written fifty or so books. Given that experience, I would say that while the things you list would sometimes be nice to have, none are essential. Take notes as necessary and maintain tiered backups (today, yesterday, last week, last month), and you should be fine. At the moment I'm working on a book on 3D printing (Futurist article available below). Initially, I gave each chapter its own file. As the chapters approached final form, I merged all into a single file, which is now (thanks to illos) over 16Meg. Tom Easton http://www.sff.net/people/teaston/
I have written one book (over 750 pages), entirely in OpenOffice.
I found it very well equipped for all the tasks I needed, plus export to PDF worked like charm. As a metter of fact it was also edited in OO, and pdf was sent straight to printing.
It can make index, table of contents, and some other things You will find usable. For example I linked over 200 images in text and not once did OO lose track of size, position or other thing in entire book.
On the other hand, I could not hold the document in MS Word to have same number of pages on several computers, it just re-numerated pages each time differently, moved images and did other nasty things, especially after thing got bigger (over 80 pages).
Besides LaTeX, I really can't think of something better than OpenOffice.
Doing a good job is like spilling coffee on a dark suit, you feel warm all over, but nobody notices.
I've worked for a number of publishers, such as O'Reilly, QUE, Dummies, as both an author and editor.
Don't use Framemaker, InDesign, Pagemaker, LaTex, or any esoteric format UNLESS THE PUBLISHER TELLS YOU.
Every place I worked for/at took WORD (MAC or Windows). They also gave you a DOT (template) to use.
As for other tools, I like Zotero instead of EndNote.
Bottom line is your publisher will TELL you what to use. If you don't have a publisher yet, Word is your best choice to start with. O'Reilly has a good DOT available to use if you don't want to roll your own.
Oh--and no matter what people tell you, OO is not Word to the publishers.
InDesign is lousy for anything beyond a few pages.
It used to be, but it has gotten a lot better in recent years, pulling in much of Framemaker's feature set. It is a viable option these days and for some projects better than Frame.
I'm a tech writer and we use Word at work. It's not as bad as you think.
Did you read his criteria? Word is pretty awful when you try to use it with versioning and it is still pretty terrible for long documents. The continuing document corruption issues for large documents, especially with images makes it a poor choice for almost any long document, IMHO.
I wish I'd known I had chosen the wrong publisher.
I published a book with SAMS (an imprint of Macmillan Computer Publishing, which is not related to the British publisher called Macmillan). I was working with some half a dozen other authors and only needed to complete a couple of chapters (the page production rate that Que require from authors is so huge that I'm sure I could not have achieved that as a sole author, at least not if I wanted to take the time to check the copy I was submitting).
The basic problem was that MCP's editors (I guess copy editors initially) loaded the text I gave them into Microsoft Word (I assume, I can't remember if they confirmed this). It immediately "corrected" all the punctuation. Since the book was about Unix, there was an abundance of single and double quotes, backticks, and so forth. They all got totally screwed up. On proof reading, I spotted these, fixed them and sent the corrected text back. Then of course they loaded the text into Word again and broke everything a second time.
The whole experience was frustrating and I was left with an author credit on a portion of a book that was riddled with stupid errors. I am embarrassed to have been associated with such a farce of an attempt at a technical book. I will never again work with any publisher in that group.
I should disclose that following publication, I had other difficulties with MCP in that they published the text a second time in another book under their Que imprint, without consulting me or paying me. They rectified that when I complained, though I didn't know to do so until I noticed my text in a book I browsed in a bookshop. So there is some subsequent bad feeling on my part, so take it as read that you're not getting a dispassionate report here. Mind you, the book was published ten years ago this year, so I've calmed down a bit now.
The list of publishers I'd consider collaborating with now is much, much shorter - only about four publishers (plus any others I don't know about - and I'm sure there are many - who will accept camera-ready copy).
You can't go wrong with latex. It is routinely used to publish 200+ page page Ph.D. theses.