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?"
Adobe InDesign (Score:1, Interesting)
Re:Adobe InDesign (Score:3, Interesting)
Microsoft OneNote is worth looking at (Score:1, Interesting)
I've used OneNote to help me collect notes, references and write chapters for two novels and multiple short stories. It's really one of the most overlooked Office applications and it's great for freeform collections of ideas.
FYI most publishers expect manuscripts in Word format, so I'd get used to that. A technical publisher may have more specific requirements. It's unlikely they will be using whatever tool you select.
I've never felt the need for automated version control. How big is this book?
Why not Word? (Score:1, Interesting)
Why shouldn't you use MS Word?
I think you'll find that a LOT of publishers *require* MS Word. Maybe not the techy ones so much but an awful lot of them won't even touch anything else (in the same way that 99% of job agencies require your CV in Word format).
Additionally, Word may have its downfalls but the older version are top-notch for book writing and do most things flawlessly (e.g. chapter/section management, markup, annotation, and index generation).
It's nowhere near the same but my father-in-law is a professional, published author (not in the techy-field, he's a teacher) with a real publisher and agent (i.e. not that self-published crap) and uses nothing but Word. And it's not because he doesn't understand the alternatives or isn't aware of the options - Word just happens to be damn good at some things.
I still have a Word 2000 CD and licence (strangley, it's just Word, not Office) that I run over Wine etc. and it's only OpenOffice 3.0 that is making think of coming off it. Some things in Word are just fantastic once you have set them up (e.g. I can just type a line, highlight it as a custom heading style and it gets assigned a chapter number, the entire documents heading get renumbered and the contents/index are rebuilt to reflect the new layout). It's a pity that newer versions are such a stinking pile.
You'll never finish it (Score:3, Interesting)
if you worry more about how to write it than you do actually writing it. Books were written with pencil and paper for centuries. Really.
And on the 8th day... (Score:3, Interesting)
...God created DocBook [docbook.org] and Subversion [red-bean.com].
We use DocBook and SVN to author/edit/maintain the MySQL Manual and related documentation.
Most of us working on the MySQL docs team also use oXygenXML [oxygenxml.com] for editing - it's neither libre nor gratis, but it's not terribly expensive, and it works well on any platform with decent Java support (one of the few Java GUI apps I've seen that really works, and works well). Handles many common XML formats including DocBook, XHTML, DITA, and TEI. You can also supply your own DTDs/schemas for custom XML formats. Includes both code and visual editing views, as well as instant validation and a built-in Subversion client. Easy to produce HTML or PDF output from XML source. Also has some nice XQuery and XSLT tools if you need them.
Re:LaTeX (Score:4, Interesting)
I've also been learning LyX and it's a WYSIWYM(ean) front-end for LaTeX. I suggest you try it.
Tools for writing (Score:4, Interesting)
Re:Shouldn't.... (Score:2, Interesting)
Re:Shouldn't.... (Score:3, Interesting)
> you could write it in Notepad or vi for all that it matters
Yup. I wrote my JavaCC book [generating...javacc.com] using vi + dbhelper.vim, DocBook, and a few little Ruby scripts to run all the example code. It's nice to be able to regenerate all the examples with a nicer format in 3-4 minutes or so. Good stuff.
OO works just fine (Score:5, Interesting)
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.
Re:You'll never finish it (Score:2, Interesting)
On the other hand, the first novel submitted as a typewritten manuscript was "Huckleberry Finn", so not everybody who thinks about new writing technology is a bad writer.
I've written six books (Score:2, Interesting)
I'm a professional, full-time author. I've also worked as a commissioning editor. I won't tell you who I am because I like anonymity and Slashdot can be a bear-pit at the best of times.
Firstly, don't be down on Word. It's the best word processor out there. It has faults, sure, but it's light years ahead of most other tools, if only because of superior changes tracking and revisioning. And I speak as somebody who writes about open source software.
But ultimately the tool you use depends on the publisher's requirements. One publisher I wrote for was a Word shop. Another used text files and CVS. I'm fairly sure a third I almost wrote for used whatever method the author wanted.
Secondly, bear in mind that authoring is extremely hard work. It's really fucking hard work. My first book was the hardest thing I'd ever done. Hands down. And I'm been through all stages of education. This things make you a better human being, of course, but you'll be left wondering how you ever managed it.
It will eat your free time. All of it. I wrote my first book while working full time in a deadline based job that left me almost no time at all (i.e. up at 6am, back home at 7pm). I don't know how I did it but I do remember that it took up my weekends, evenings and all my vacation time. I'm single. if I'd had kids, I've no idea how I'd have done it.
Thirdly, writing is only the start. Actually, just a small part of the entire process. You need to revise it, then you need to respond to editing comments. And it's not over then either. Once the book is published you will need to help publicize it, because the people who work in publicity for publishers usually know very little. Some books are marketed by virtue of being from certain publishers, such as O'Reilly. But most books have to fight for whatever attention they can get. People believe that "if you build it, they will come". The truth is the inverse of this. If you write it, nobody will know it exists until you spend countless hours telling them over and over and over again that it exists.
Expect to blog, expect to run excerpts, expect to do podcasts, expect to try and get as many mentions as possible on Digg or Reddit (which means, effectively, putting your life in the hands of disposed teenagers). A Slashdot review is nice, but that means putting your heart in the hands of disposed 30 year olds who truly believe they know everything.
Expect to get addicted to Amazon sales rankings.
So, in a nuthsell, it's fucking hard work, and the job is about 50% finished when the book rolls off the printer production line. Oh, and did I mention that you will NOT make any money? Seriously. You won't. You might make pocket money. Get as much money up front as you can in the form of an advance. This is especially important in our current economic climate when many publishers will probably go bust.
Re:LaTeX (Score:2, Interesting)
The absence of a spellchecker is the smallest problem with latex. Spellchecking can be done by your favorite text editor (man vim) or external tools such as ispell/aspell. Depending on what you want to do "customization" can come with an extremely steep learning curve (sometimes as steep as running straight into a wall of solid rock):
- use of custom fonts is tricky for the beginner and even the advanced user usually won't try.
- exotic page layouts (i.e. everything latex doesn't "naturally" provide such als multicolumn layout with boxes/graphics spanning multiple columns) are hard to achieve even for experts.
- basically everything that's not provided by the basic set of packages will be tricky at best.
If these limitations are not an issue to you (i.e. you just want to get the job done with a pretty standard book layout) latex is definitely worth looking at. Otherwise look at dtp tools such as scribus or framemaker. But be warned: although the gui makes them _look_ easy to use i find it actually much harder to get decent results out of them than out of latex.
The unbeatable advantage of latex (and the reason more and more people are switching over from word to my latex-templates at work ;) is that it integrates extremely well with versioning tools and once you have written a decent makefile around it in order to include graphics and the like you'll go to great lengths before using anything else. Also, the generation of pdf with index and the likes is much easier than anything else i have tried.
The most important thing: who to work with? (Score:5, Interesting)
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).
Re:LaTeX (Score:3, Interesting)
Most serious academic work is done in LaTeX. My papers are all typeset in LaTeX. I use emacs to do it. The software is free (in all sense of the word), and the documentation is plentiful.
ispell will spell check it. You can run that in emacs as well, or just invoke from the command line "ispell -t". You can draw figures in any graphics program, export to eps, and then include them in your document. Tables, math, text, sections, all beautifully laid out for you.
So come on, join us Tex heads! As for the learning curve, if you can't grok LaTeX, you probably should not be authoring tech books.
Do the Jack Kerouac thing . . . (Score:3, Interesting)
"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?"
Learn from a master, Jack Kerouac, from Wikipedia, about his book "On the Road":
"He completed the first version of the novel during a three week extended session of spontaneous confessional prose. Before beginning, Kerouac cut sheets of tracing paper [11]into long strips, wide enough for a type-writer, and taped them together into a 120-foot (37 m) long roll he then fed into the machine. This allowed him to type continuously without the interruption of reloading pages."
Even if O'Reilly turns down your manuscript, they will laugh their asses off when that long roll lands in.
As a published author/editor (Score:3, Interesting)
I edited a book on business and legal issues in game development [psychochild.org]. Not exactly a tech tome, but I'm a programmer by training, so I hope I can share some insight.
The important thing, as others have mentioned, is a question on if you have a publisher, if you are going to look for a publisher, or if you want to self-publish.
If you are going to self-publish, take a long, hard look at what you're doing. Does this have to be in book format? Or, would setting up a convenient website be better? There's a certain cachet to having a published book, but for a lot of tech things I'd prefer to have an online reference. Even if you do have a compelling reason to put the work into dead tree format, having a companion website is highly advised.
If you have a publisher or want to find a publisher, I'd recommend doing that first. When my co-editor and I thought about our book, we wrote up a Table of Contents for the book and pitched that to the publisher. We went to a publisher of other books on the game industry and they were really receptive to our idea. If you're going to write the book on your own, you might want to write up a chapter in addition as you approach publishers.
Once you find a publisher, they'll give you the information you need. They might want everything submitted in Word format, as ours did. Use the tools they recommend to ease the process. The last thing you want is an irate publisher, trust me on this one.
Finally, work with an editor. If you're self-publishing, get an editor! Another pair of eyes with the ability to go through your work with bloody red pen is absolutely vital to ensure that you aren't writing boring crap. If you're working with a publisher, try to get on good terms with your editor from the start and build some respect both ways. The editor's job is to improve your work, so understand that every nugget that is created by your keyboard isn't always made of gold. Your editor is vital to the long-term success of your work.
Here are some lessons I learned along the way:
* It takes a lot of time. More than you probably think right now. Even though I was "only" an editor (ha!) for chapters contributed by others, it was a full-time job and then some. Expect to write every waking moment you're not doing something to ensure your survival (eating, sleeping, earning money). Do whatever you can to stay focused, because it's going to take a lot of work, and a lot of times it will be boring. Re-writing a chapter for the fourth time in so many weeks because it just doesn't seem to want to come together defines "test of endurance".
* Don't expect to get rich. Some people get into writing a book thinking it's the path to riches; it's not. A book that does well sells a few thousand copies. But, as one person put it, a book is an awesome business card. ;) Use the book to open doors and provide other opportunities for you that can help you achieve your goals.
* It really is awesome to have a published book with your name on it. It's a tremendous sense of accomplishment to have your book sitting on your bookshelf.
Hope that helps a bit. Good luck with your work!
Re:Why not Word? (Score:1, Interesting)
Here is my experience with Word 2000 and earlier:
Troff was used by W. Richard Stevens (Score:3, Interesting)
-W. Richard Stevens, author of 7 popular technical books. [R.I.P.]
Re:The most important thing: who to work with? (Score:3, Interesting)
Bear in mind that there are doubtless a number of publishers who are perfectly capable of getting it right, but having been burned already, I'm probably over-cautious. In alphabetical order, the publishers I'd be interested in working with now are Addison-Wesley, O'Reilly, Prentice-Hall and Wiley.
Maybe also Morgan Kaufmann, though that's really based on the astonishing quality of some MK books I've read (e.g. "Advanced Compiler Design & Implementation" by Muchnick) more than their production methods, whatever they are. I would guess that Wrox Press's methods could have been quite workable for technical authors, but the point is moot since they went bust in 2003 and were acquired by Wiley.
Re:Publishers provide this information (Score:2, Interesting)
There are many PDF to Word converters. Solid Converter, although paid, never failed me, even with complex tables and graphics.
I use Latex myself, but I can submit my reports as PDF so the problem never came to me, but there are Tex to Doc and Rtf converters out there.
Using a tool you're not comfortable with to write a whole book just because of the output format seems foolish to me. The time you save by using what you like more than pays of the time required converting and adjusting the display.
Re:Whatever the publisher wants (Score:1, Interesting)
If you ask a publisher they will probably say doc. If you ask if they take latex, quite a few tech book publishers will say yes and provide the style files.
Re:If you have a publisher, ask them. (Score:2, Interesting)
I've written about 20 tech books for major publishers. They all used MS Word. It's the publisher's call. If they use Word, then the editors will use Word - including the tech editor and copy editor, who will both use Word's comment feature to enter their comments.
Spend what seems a disproportionate amount of time writing the table of contents. That organizes the whole book for you and makes everything following flow better.
Gear your writing for the target audience. If the book is for a beginner/intermediate level audience, write it that way. The book isn't a vehicle for your knowledge. The book is intended to teach the reader a topic, not to inform the reader how much you know about the topic.
From the article submission:
> Did you encounter any surprises that you wish you > had known about back when you started out?
Yes. One big surprise is how little money you'll make
Re:Mellel (Score:1, Interesting)
OpenOffice.org (Score:3, Interesting)
I've written three tech books and edited five, all with OpenOffice.org. The publisher's people all used Microsoft Word. No problem.
Write each chapter as a separate file.
Ideally, the publisher will handle the indexing and you won't.
Indexing is best done manually, anyway. It's not that hard. I've done it for several books, working from galleys.
Re:OpenOffice.org (Score:2, Interesting)
I used OpenOffice for my third book (600 pages). It was a big mistake. When I was done, the publisher reminded me that they wanted the output in Word format. I converted the OpenOffice format to Word, and the result was terrible. This is because I tend to use lots of complex layout features, with nested tables, placement of text boxes in the margin, etc. These kinds of layout features are very important for book design today: the most readable and successful technical books have sophisticated layouts, and the publisher will not generally do this part for you.
OpenOffice has improved alot since then (three years ago), but even so, if you are doing a large manuscript, use the tool that the publisher wants. You can't leave layout to them anymore: use their tool and styles, and do your own layout.
By the way, I have used OpenOffice to generate PDF files, and it has many glitches. If you are generating a large manuscript as a PDF, the likelihood that you will run into a glitch or two is high. E.g., their PDF generator does not seem to render properly when images are placed at fixed positions relative to a paragraph. I had problems with that. And for a production PDF, everything must be perfect.
For my most recent book (500 pages), I used Word from the outset, and did the entire layout myself. Word is a terrible tool to use for that, but it worked. I had the layout control I needed, even though it is flaky (text boxes move suddenly if you change anything). There are lots of quirks that make Word unsuitable for a large manuscript, but it can be made to work (with lots of frustration).
I once used Framemaker to do a book (my second book, the 800 page one), and that was a good experience.
Nowadays, I wish I had a tool that allowed me to do wysiwyg layout (very important for a good layout), but that also generated DocBook XML. That way I could publish the content on the web as well. But I don't know of a tool to do that. Even better, it would be nice to have a tool that would maintain the book book as a manuscript (with print layout) and an online wiki....
OpenOffice claims to generate DocBook output, but I tried it and had problems. It was a new feature when I tried it: maybe it works now.
I am not a proponent of using the Latex tools. I must say that I am not very familiar with them, so I am not one to comment. But they seem not to be layout oriented, and as I have said, today the visual layout is very important. A book is no longer a stream of text with pictures interspersed: it is a complex mashup of text and pictures. To create that, you need a layout-centric tool.
- Cliff
Re:If you have a publisher, ask them. (Score:5, Interesting)
Sucks, but there it is.
I wouldn't say "sucks", but I work on the editing and layout end of the process. Having an author kibitzing on the layout is what sucks. What we need from the author is a functional layout: so we know what level of heading is intended; not "18 point bold Arial".
I've worked on hundreds of books and I cannot recall ANY authors, including University professors, who had a clue about how to use their tools of choice (as they all had written their manuscripts before bothering to consult the publisher), they all used Word, and most of them like a typewriter. None had a clue what a "style" was or how to use it consistently. You were likely to find paragraphs of body text styled as "Heading 1", reformatted to be 12 point Times. I normally spent half a day cleaning up crap like that before I could export the file out of Word and start the actual layout.
The ones who did think they knew about layout were even worse though. They try to tell me that "Arial is a great body text", "two spaces are required after a full stop", "underlining is how I want to emphasise", "the text should be at least 14 points to make it easy to read", "my name should be bigger", etc, etc. If you don't know why this kind of thing causes DTP people to grind their teeth, just take my word for it. You do require a degree of stubborn egomania to get a book written and published, but you also have to know when to take advice from people who have more experience.
I used LaTeX and couldn't be happier (Score:4, Interesting)
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.
Re:I used LaTeX and couldn't be happier (Score:3, Interesting)
Re:Advice from an Editor and Writer (Score:2, Interesting)