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 are dead serious about writing, and don't mind paying for the best tools, Mellel is for you. It is a word processor application geared towards professional & academic writing, and the features are quite convincing. See http://www.redlers.com/mellel.html for more.
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
yeah, use word to write a book and paint to make the cover, because there's nothing more professional and gratifying than wasting your time on a WYSIWYG editor checking that the whole book is correctly formated (manually by you btw). ever heard of latex and other tools designed for this purposes?
In my limited experience of two book chapters, it depends. For a "large chunks of text interspersed with the occasional equation" style of book word is pretty much in it's element. But if you have lots of equations, and particularly if you have lots of *inline* equations, then word is still seriously lacking: entering equations is painfully slow and the result are, diplomatically speaking, readably hideous.
There are quite a few reasons not to use Word, particularly for technical books. It's one thing if the publisher *requires* it (and it's even worse if they use one-chapter-per-file, as cross-referencing flies out the window).
It's much better to separate the content from the presentation, and way more useful. It's also substantially easier to create aggregate documents outside of Word.
Personally I prefer DocBook, which I'll often pre-process to get marked-up source code samples, dynamically-generated images, and so on. Latex is obviously a similar, good choice.
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.
That's the sort of thing I use Scrivener for:
http://www.literatureandlatte.com/scrivener.html
Mac only, though. But very nice.
If you're on a Mac, I can recommend Scrivener.
It is for text, so if you need something that does your layouting and figures and tables as well, it's probably not right. But I love it for its organisation features, where your book is treated as individual chapters and sub-chapters that you can drag around and sort as you like, something that's saved me a loot of copy & paste when you realize that this part would make a much better chapter start and that part over there really ought to be explained earlier, etc.
Assorted stuff I do sometimes: Lemuria.org
I'm amazed it hasn't been mentioned (that I see). Perhaps not suited to drafting stuff, but for final page layout it seems to be perfect.
InDesign has changed a LOT in the past two iterations. CS4 is a completely different beast from CS2 or CS1 (or every CS3!), thanks to the absorbtion of various features from Frame Maker.
http://www.troff.org/pubs.html * Advanced C: Tips and Techniques * Advanced Programming in the UNIX Environment * The AWK Programming Language * The Complete FreeBSD, 4th Edition * The C Programming Language * The C Programming Language, 2nd Ed. * C Traps and Pitfalls * Collins English Dictionary & Thesaurus, 2nd Ed. * Collins German Dictionary, 4th Ed. * Compiler Design in C, 2nd Ed. * Compilers: Principles, Techniques, and Tools * Computer Networks, 3rd Ed. * Computer Networks And Internets, 3rd Ed. * The Design and Implementation of the 4.4BSD Operating System * Effective TCP/IP Programming * The Elements of Programming Style, 2nd Ed. * Hands-on Networking with Internet Applications * The Internet Book: Everything you need to know about computer networking and how the Internet works, 3rd Ed. * Internetworking With TCP/IP Volume I: Principles Protocols, and Architecture, 4th Ed. * Internetworking With TCP/IP Volume II: Design, Implementation, and Internals, 3rd Ed. * Internetworking With TCP/IP Volume III: Client-Server Programming and Applications, AT&T TLI Version * Internetworking With TCP/IP Volume III: Client-Server Programming and Applications, BSD Socket Version, 2nd Ed. * Internetworking With TCP/IP Volume III: Client-Server Programming and Applications, Linux/POSIX Socket Version * Internetworking With TCP/IP Volume III: Client-Server Programming and Applications, Window Sockets Version * Internetworking With TCP/IP Volume III: Client-Server Programming and Applications, Window Sockets Version, International Ed. * Learning XML (Guide to) Creating Self-Describing Data * More Programming Pearls * Network Systems Design Using Network Processors * Network Systems Design Using Network Processors, Agere version * Network Systems Design Using Network Processors, Intel 2xxx version * Operating System Design - The XINU Approach * Operating System Design Volume 1: The XINU Approach, Macintosh version * Operating System Design Volume 1: The XINU Approach, PC version * Operating System Design Volume 2: Internetworking with XINU * PONS GroÃYwÃrterbuch für Experten und UniversitÃt, Englisch-Deutsch/Deutsch-Englisch, m. Daumenregister u. Beiheft * Porting UNIX Software * The Practice of Programming * Real World Linux Security, 2nd Ed. * Software Tools * TCP/IP Illustrated, Volume 1: The Protocols * TCP/IP Illustrated, Volume 2: The Implementation * TCP/IP Illustrated, Volume 3: TCP for Transactions, HTTP, NNTP, and the UNIX Domain Protocols * UNIX in a Nutshell: System V Edition * Unix Network Programming * UNIX Network Programming, Volume 1, Second Edition: Networking APIs: Sockets and XTI * UNIX Network Programming, Volume 2, Second Edition: Interprocess Communications * UNIX Power Tools, 2nd Ed. * The UNIX Programming Environment * The Unix Text Processing System * VPNs Illustrated: Tunnels, VPNs, and IPsec * Programming in C++, 2nd Ed.
To echo several comments I have seen, I would start by finding out what the publisher wants.
With that said, at least for technical papers LATEX is often the way to go. It is free and designed for mathematical/technical papers and books. Especially when used in conjunction with BibTex it is excellent at handling very large documents with indexes, tables of contents, and references. There are several good Latex Editors. For short pieces I personally use NotePad++. For longer pieces you may wish to consider something like Eclipse with the proper plugins which makes it more user friendly and can work with version control software which can become important on large projects, especially when you get other people involved (and there will almost always at least be an editor if not several editors and advisers on a large project).
even easier: get a box of dot matrix paper.
Do you even lift?
These aren't the 'roids you're looking for.
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 wrote a book a few years ago.
That was in Office v.X on an old PowerBook (I even started in the original "can't print" beta of Word v.X).
http://www.amazon.com/Compression-Great-Digital-Video-Techniques/dp/157820111X/
And I've got a couple due in 2009 for different publishers, so this has been much on my mind.
Based on a lot of the other comments, people are really focusing on the formatting aspects of the workflow: Latex, FrameMaker and all that. But if you're writing a book for a standard tech publisher, you likely will never even have a direct conversation with whomever does the layout. You turn in structured text and figured to an editor, when then passes it off to layout after editing.
And if it's any kind of a series, they'll be doing formatting according to a well defined template and style that'll map to the styles in the document you give them.
So, the actual workflow is that you get a Word template, and write everything in there. The key thing is to follow the Styles religiously - every paragraph should have one as you type it. Think writing in old school HTML, or XML to someone else's Schema.
Also, try not to even think about formatting; there's no saying what goes on what page based on Page Preview in Word or alternative. If you want a new section, use a section break. This is object-oriented writing, where you're really trying to get the content into the right structure for easy processing later on.
I recommend working in Outline and Normal/Draft mode only, since that's where you see the structure of what you're doing. Personally, I'm a born again believer in outlining. I outline a chapter, and then jump in and write the part of it I'm thinking about at the moment. With the outline there, it's easy to realize I need to introduce a concept earlier in the chapter and then jump there and do a quick sketch of it, since the earlier section already exists in the structure. The act of writing an outline also helps define all the stuff you didn't know you needed to figure out.
But don't be a slave to the outline as it exists; structure can need editing as much as prose. Don't be afraid of moving sections and chapters around as helps you communicate better. That's a lot easier to do early in the process.
My video compression blog
I've now written two books that were published by major New York publishers, co-written another book that was used to launch my publishing company, and published two additional books by somebody else under my publishing company. So, speaking from both sides of the fence, there are a few things that will be handy for you to know...
What you do in part will depend on if you have a publisher already, or if you are writing the book to try to sell to a publisher later. If you've got a publisher already, as has already been said on here, ask your publisher for guidance - they will provide everything you need, and if you have questions, your editor is there to answer them.
If you don't have a publisher, one of the most important things is to realize that you are writing a manuscript, not a typeset and formatted book. This is incredibly important - all-important, in fact. If you hand the publisher something that isn't formatted as a manuscript, when it comes to a lot of publishers, you are essentially shooting yourself in the foot. Formatting the book is their job, not yours.
So, for a manuscript, what is usually going to happen is that an editor is going to read a printed copy, and make lots of notes on it. It must be double-spaced (so that notes can be made between the lines), in an easy-to-read 12-point font. Courier is preferable, but Times New Roman is acceptable too. Page numbers will be on the top right, and your header will be on the top left, with an extra space in the header to make the manuscript easier to read. Each chapter should also begin around the middle of the page.
When it comes to word processing programs, flexibility is key after a certain point, so that you can provide whatever file format is requested. But, when it comes to the writing itself, use something that you enjoy working in, and that you find easy to use. In my case, I use WordPerfect, in large part because once you start typing, it feels like a typewriter, and can also save in just about any format I need.
(It is also extremely powerful, and I use it for typesetting and indexing, but that is beside the point for this discussion.)
One thing that is handy to know regarding images - for an image to print properly, the image must be 600 dpi (dots per inch) - the best type is a high-resolution TIF file.
Indexing is not your problem, but you can make it easier for the publisher. The way you do that is to make a list as you write of important key words, and give that list to your editor for the indexer. That way, whoever indexes the book has a cheat sheet of sorts, and can do most of the index using a find function. Considering that indexing has to be the single most grueling, boring, and tedious job in all of publishing, the indexer will be very thankful for it.
As far as keeping organized goes, not much to say there - keep organized. You're going to be handing a long document over to your editor to be worked on, and your editor should be spending his or her time working with your words, not fighting with the document itself. Take note of where each figure is supposed to go, and be prepared to provide that information.
And I think that covers the tips I'd want to pass on...
Robert B. Marks
Author, Demonsbane in Diablo Archive
...tech/IT security books, I've run across many pitfalls along the way.
*) If you're just starting out, use Word. That makes it easier to pitch to publishers. :(
*) If you have a publisher, they will give you a Word DOT template.
*) You can write the material in something else, but you will almost always have to submit it in Word.
*) The pay sucks and so do the hours. Many tech book publishers give a three month window and around $5,000 per book. At 20 hrs/week, that's roughly $20/hr. And you'll sink many hours into it.
*) As a new author, you will be taken advantage of. You may be brought in on other projects and asked to write a quick chapter in a week, even before a contract has been signed. You may receive an email from your tech editor about changes with a deadline of _1 hour_, while you're in the middle of your day job.
*) Make sure you're writing the book for the right reason. If it's for money or esteem, the book will stink. If it's to generally teach someone a concept, it probably will do alright.
*) Sales on tech books stink. Don't expect any royalties unless you're a big time speaker or your book is picked up for a university course. Most tech books expire within six months, so there's a strong push to write the book months before the technology becomes popular, and then ride that wave.
*) Get a second pair of eyes on everything. There may be some little tool or process that everyone in the world knows about except you. When you write on another one instead, you will ostracize many of your readers.
*) Keep humor to a minimum. Most people stink at humor, even if they think they're funny.
*) Give lots and lots of case studies and examples.
*) Double check and triple check everything that is sent to the publisher. I've been screwed MANY times by this. Go LINE BY LINE, WORD BY WORD, through the whole thing. In one case, the copy editor accidentally removed a paragraph and repeated the previous one twice. The paragraph she removed was the one that gave credit and citation for the entire chapter to the original tool authors. Quite a few were pissed off to see me writing about a tool and not mentioning who wrote it and where it came from.
*) Don't send anything to the publisher unless it's exactly what you want in the book. I made this mistake big time. I wrote a quick chapter, threw in screenshots for everything, and submitted it for them to review. My plan was for them to review it while I worked on redacting information from the screenshots. Chapter went through fine, I sent my new, redacted images, and they published the old ones instead. So, my entire familys' names and emails are now Google-searchable from that book
That's it from the top of my head. I got my name on some books, I met some good people, and I had some fun. But, the publishers eventually wore me down.