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
I'd recommend www.thepiratebay.org.
There's also TorentReactor too for nice compilations.
Oh wait... you want to MAKE books? Oh, nevermind.
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!
On the contrary, thinking of asking slashdot surely means he's *very* qualified.
"linux is just DOS with a UNIX like syntax" -- Galactic Dominator (944134)
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.
Use latex and a Makefile.
Set up targets for every chapter separately; add features / other make targets as you go along.
Stephan
http://stephan.sugarmotor.org
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.
Key point: InDesign is for *layout*, not for writing. The design goal of InDesign and similar programs (Quark Xpress, Scribus, etc.) is to allow you to place regions of text and/or images exactly where you want them on the page, to twist them into exotic shapes, to apply fancy colored borders or backgrounds, and generally to take the existing content and make it artistic. I would never use one of these programs to write a book, unless it were something like a magazine where the text is split up into little oddly placed regions, and even then I'd write the text itself in some other program before copying and pasting into the layout editor. (I speak from a few years of experience with InDesign and Scribus, btw)
I have two books, one in its second edition and one in its first. Both have lots of equations. I insisted on using LaTeX and having the books typeset in LaTeX, the publisher agreed, and it's one of the best decisions I've ever made.
Here is why I'm happy: THE EQUATIONS IN THE PAGE PROOFS ARE THE SAME AS THE EQUATIONS IN MY ORIGINAL MANUSCRIPT. I can't tell you how important that is. Most editors and proofreaders do not have a clue about technical material. If you write in Word or some other format that is "rekeyed" by the publisher, I guarantee that by the time you get to page proofs, many of your equations will be unrecognizable, and you will go through hell trying to straighten things out. The publishers insist that they can avoid this problem, but friends who are authors and who did not use LaTeX assure me that the publishers mess things up. In my case, various things were fouled up (graph legends for example were frequently reversed because the graphs had been redrawn), but not the equations.
Lots of folks here are saying to use what the publisher tells you to use, they have a system, etc. I had five publishing houses (three commercial and two university) offer me a contract, and all agreed to produce the book in LaTeX. They just contract out the compositing. this may vary by publisher, but in my case, it was not a big deal. YMMV.