Tools & Surprises For a Tech Book Author? 325
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?"
Publishers provide this information (Score:5, Informative)
Check out the O'Reilly website:
http://oreilly.com/oreilly/author/ch02.html#tools
Mellel (Score:2, Informative)
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, ask them. (Score:5, Informative)
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.
My own experiences writing a tech book (Score:5, Informative)
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
LaTeX (Score:5, Informative)
Re:LaTeX (Score:4, Informative)
Re:LaTeX (Score:3, Informative)
Re:LaTeX (Score:2, Informative)
Re:LaTeX (Score:1, Informative)
In other words, working in LaTeX is like programming. Instead of WYSIWYG, you have a plain text source file that gets compiled into the completed product.
Which means that your whole programmers toolkit is good.
Want to change something using a regex? Perl or sed to the rescue.
Want spellchecking while editing your file? Well, if you use emacs just his M-x flyspell-mode.
Want reasonable version control? Basically everything is good at version control on text files. They are diff friendly, and you can even use cool features like git log -Sbarnacle to find all changes you made that included the word barnacle.
If you're not already an expert at the whole cadre of text manipulation tools I'm talking about, you might be better off with an "IDE" like Word or one of the Adobe products.
Re:LaTeX (Score:5, Informative)
Re:Why not Word? (Score:1, Informative)
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?
Re:If you have a publisher, ask them. (Score:5, Informative)
I've written (and edited) tech books for major publishers (SAMS, Addison/Wesley, Pearson). I have to agree with the parent: it's not your call.
While you can write your book in anything you want be prepared to use THEIR tools for going back-and-forth with their copy editors, tech editors, and typesetters.
If you're comfortable in vi and using markup, that's great. However, don't be surprised when a publisher insists you use a Microsoft Word template and turn on document revision control for your chapter submissions. You may wind up taking your beautiful markup and mashing it into Word before sending it. Your proofs may come back as really awful Adobe Acrobat PDF files that make Foxit crash. Tough. Suck it up.
Producing ideas and words is your problem. Figuring out how to pass them between multiple people/departments/companies to get a book printed is theirs.
Re:Why not Word? (Score:1, Informative)
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.
Re:LaTeX (Score:3, Informative)
There may be better tools out there if you have a big budget, but I'd have to agree. I got sick of word and its quirks when writing my thesis (sort of a technical book if you want to think of it like that). Emacs and LaTeX were a life-saving combination. Bibtex took some getting used to for the indexing, but that was the hardest thing to learn.
Formatting is easy. Large projects are easy. It copes with all the major image formats. And if using a text editor is not your thing, there are pseudo-wysiwyg gui's available.
On a side note, there are also (problematic) tools to convert your document to html and many other formats once you have it in tex.
Re:Why not Word? (Score:1, Informative)
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.
Comment removed (Score:5, Informative)
LaTeX + make (Score:4, Informative)
Use latex and a Makefile.
Set up targets for every chapter separately; add features / other make targets as you go along.
Stephan
Re:Adobe InDesign (Score:5, Informative)
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.
Re:LaTeX (Score:4, Informative)
Re:LaTeX (Score:3, Informative)
[Blink.]
No, don't do that. Just use ispell -t for spell-checking, or edit your text with Emacs.
Re:Tools for writing (Score:4, Informative)
That's the sort of thing I use Scrivener for:
http://www.literatureandlatte.com/scrivener.html [literatureandlatte.com]
Mac only, though. But very nice.
Scrivener (Score:3, Informative)
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.
Scribus (Score:1, Informative)
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.
Re:LaTeX (Score:3, Informative)
One minor point about LaTeX; it's a language, so if you are a programmer, expect to get sidetracked on issues of making it do exactly what you want, for no good reason other than the fact that for a programmer, that's fun. I know that when drafting my first book (that one was never published) I spent too much time crafting a spanner to put in the margin to indicate that that paragraph needed further work. Getting the spanner to face in opposite directions depending on whether it was on an even or odd page was a lot of fun, though.
I would post the finished macros, but the Slashdot lameness filter thinks there are too many line breaks between the LaTeX commands.
Re:LaTeX (Score:5, Informative)
emacs, latex, auctex, flyspell -- wonderful combination. Oh, and you'll probably want git/svn for revision control (as suggested previously). There's also a latexdiff program floating around that can put changebars into your output file.
Flyspell allows you to have the wavy line spellchecker functionality that is fairly common now. It distinguishes between non-dictionary words that appear only once and non-dictionary words that appear more than once.
No makefile is necessary if you're using auctex. It's just C-c c for latex, bibtex, latex, latex, (pre)view.
The makeidx package allows you to create indexes (e.g. \index{ancestry!genomic}).
Yes, it's a learning curve, and the best way to start with emacs/latex is to work off some already written latex files, but the results that come out the other end are worth that effort.
Re:Advice from an Editor and Writer (Score:2, Informative)
InDesign has changed (Score:2, Informative)
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.
Re:Troff was used by W. Richard Stevens (Score:3, Informative)
Whatever the publisher wants (Score:2, Informative)
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).
Re:Do the Jack Kerouac thing . . . (Score:2, Informative)
even easier: get a box of dot matrix paper.
Go with latex (Score:4, Informative)
Re:Adobe InDesign (Score:3, Informative)
Re:My own experiences writing a tech book (Score:4, Informative)
If you use Word to merge multiple document files into one, will it update the main document correctly whenever you edit one of the other document files?
Yes and no.
If you link the file -- that is, create one "master file" with a bunch of "subdocuments" -- then yes. But you also historically increased your risk of corruption. (Don't know if it still does this in 2007 -- so much has changed, there hasn't been enough time to feel out all the quirks.)
However, if you just "insert file", it doesn't. Word read the file you pointed it at, and inserted its contents into the file you're working on now.
"Premature formatting is the root of all evil" (Score:3, Informative)
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/ [amazon.com]
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.
From the PoV of both author and publisher... (Score:3, Informative)
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...
From an author of six... (Score:3, Informative)
...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.