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?"
Steep learning curve, but it's a breath of fresh air compared to Word.
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.
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
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?
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
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.
Being 'tech-savvy' and knowing what is available are two different things. Or are you all knowing and instantly know all the best software out there to use?
Fly me to the moon Let me sing among those stars Let me see what spring is like On jupiter and mars
Well as a mathematician I believe in LaTeX as the end all for typesetting. It does all the things you asked for, and it does them well. And it makes math so pretty...
...a low ID owner such as yours presumably have enough Slashdot-savvy to NOT have to ask this?
but well, at least you've read the FA! ;-)
@neonux
If you are writing a book for ms press dont be surprsed if it ends up with many spelling mistakes and code ommissions, it's just "one of those things".
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)
Check out docbook - an XML DTD. A text editor that can do programmable macros would be handy, so you can make keyboard shortcuts for the most common tags ("<para>", etc) - or one that already has support for docbook built in. Just mark it up as you write. It's easy when you get into the swing of it.
Being 'tech-savvy' and knowing what is available are two different things. Or are you all knowing and instantly know all the best software out there to use?
If you have a book contract, the publisher has requirements for what they want. If you don't have a contract, you could write it in Notepad or vi for all that it matters....
I wrote my first one primarily using vi.
tEx... :D :D :)
if you are writing a Dummies book, use LatEx...
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.
...God created DocBook and Subversion.
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 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.
Il n'y a pas de Planet B.
One word: latex. It does all everything asked, produces elegant results, has packages to tackle just about every sort of package or diagram you could want, and it's free. Not only that, but because you write everything in plain text and then "compile" it you won't have to deal with the old Word/Works/Other(TM) nightmare of "the program" crashing and wiping out the last hour/day/week of work in the process.
Try www.ctan.org for more information.
And wise enough to know when to ask for help, something too few tech people know how to do...
...why *don't* you want to use Word? It has the features you are asking about (minus version control, there are other solutions for that). I've used it for my own book, as well as contributions to about a dozen others I've contributed to. Honestly, it depends on whether you're thinking about self-publishing or working with a publisher. Here's my two bits, from the perspective of working with a publisher:
In particular, the tracking feature is extremely handy (required, actually) when going back and forth with a publisher or technical reviewer. But at least in my case, the other features you asked about didn't come into play for me at all. My publisher only wanted very basic formatting. For instance, there was no need for me to do anything but use the template they supplied. Images were supplied separately in EPS format, and just referenced in the text through a marker (*** Image 03-02.eps ***). They didn't want me to embed them in the document itself. If I wanted a sidebar, I'd just mark it: *** Begin Sidebar *** Each chapter was a separate, numbered document, and I wasn't required to create or maintain a table of contents. Formatting requirements were basic: 12-point Times New Roman for text, Courier 10 pt for the code, double-spacing, as well as some details about how to mark sections and subsections.
Essentially, if you are working with a publisher, they'll probably handle all the formatting and layout issues, and will likely ask you to submit your work in Microsoft Word format. Like it or not, this is what many publishers expect (at least, the two I've worked with). If you're not comfortable using a Microsoft product for whatever reason, then simply use OpenOffice. It's a fine product as well, and should have no problems importing and exporting basic Word documents for when you need to collaborate with the publisher.
Don't over-think this - any of the major word processors used today should be perfectly adequate for your needs.
Irony: Agile development has too much intertia to be abandoned now.
Yes, but that wouldn't make the man's life any easier, or even be very productive.
Don't equate "technical" with knowing every bit of software out there. The author of the question didn't actually say what they are technical in - perhaps they are an expert in LDAP, and may not know much about DTP. Let's put it this way: I'm pretty technical, but I don't pride myself on my awesome ability to use Microsoft Word!
XML is like violence. If it doesn't solve the problem, use more.
You may just get a goatse link in your book.
Also, provide all the "citation needed" requests.
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/
Screw the learning curve, use LyX. It is a front end to LaTeX that takes care of almost all of the complicated, but still lets you add complicated things (or even export to just LaTeX code) if you want to. I wrote my thesis using LyX and I was able to avoid 95% of the problems that I saw other students have.
I have found that Word worked just fine for my book... http://www.elevatorpitchessentials.com/ ...which is more of a business book (but I was forced to deal with the same issues).
The biggest thing to keep in mind is that the publisher is going to define everything using styles, so you really just need to worry about content and not formatting. You could almost use a very simple text editor.
I would ask your publisher, if you have one, what format they prefer and what makes their life easier from a layout standpoint. Do they want you to define code samples using a different style or font?
I can also give you some information on self-publishing if you want, as that's the route I chose.
Choosing a word processor to use is important. I helped write a textbook published by Springer. They not only insisted on MS Word, but wanted its writers to use a template designed by them. We started to write the book in MS Word without checking with them first. We had to convert the document to make use of their template.
Face it, you will be dealing with business types and often they will insist on a specific word processor. I wasn't very happy about using a MS product but as I wasn't the primary writer, the decision was not in my hands. Some publishers are more flexible than others. Check first before you get very far into the writing process.
Not in today's market. Many publishers want books out there really fast, so they are willing to take anyone who can spell the product's name. All you need to do is be able to take existing documentation and put it together somewhat coherently without really understanding what it means. I just did a tech review of a book on an open source admin product and it was obvious from the examples that the author had (probably) never used the product in the real world and possible never even administered a Linux system. I am actually glad that I was not mentioned for having worked on it.
> you could write it in Notepad or vi for all that it matters
Yup. I wrote my JavaCC book 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.
The Army reading list
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.
Ironically it was MS Word.
If you are using a publisher, they'll dictate what you use.
If not, use LaTeX. Any book that is complex enough to be worth reading will exceed what any word processor can do almost immediately.
My advice is not to waste your time writing for a publisher. The odds of your book selling enough copies to pay back the advance are not in your favor, and by the time you factor in opportunity costs, you'll probably lose money for every hour you spend on the book. You'll come out ahead writing a book for yourself and publishing it as open source.
Turn off "Smart Quotes" in WORD if you use it. They play havoc with many other programs that might be needed to paste your manuscript into during the publishing process. Such as adjusting the font or point size, justification, text spacing and little things like that.
.pdf, Kindle, Amazon or the like which still like ASCII. Don't scoff, this is getting more popular as traditional publishing houses fall behind the curve of internet paced markets. e-Books are the future.
Saving your work in ASCII is a real good thing as everything can read ASCII without any trouble at all.
Spelling and grammar count for a lot also.
Most of all, read your markets "Writers Guidelines" thats where they tell you all these little things you really do need to know. When in doubt, ask. (This is making the assumption that you have a market or publisher already picked out. If not see comments on ASCII above)
If you don't have a market picked out consider the self published e-text market. If you go that route you are talking
Hope you do well with your project!
Use Word...
...or if you have some strange issues with Microsoft, or don't have access to a native version of Word, Open Office will work. Word is actually quite good at this sort of stuff, plus this will give you the most flexibility in the long run (at least as far as publishers go). The exception is if you are self publishing or handling copy edit/tech edit/ and layout yourself. See the problem with other tools is that you will find that most production people (including copy/development/ and many tech editors) are trained to use Word, and using something else will a create huge workflow issues and may require some sacrifices in the production process, resulting in an overall negative effect on both the timeliness, editorial effectiveness, and cost of producing your book.
Now many publishers are at least considering the use of docbook or a similar XML type format (since often most books end up in XML for easy output to various print and online mediums), but for now it's just not an ideal format either since the tools haven't evolved to be that useable for many editors. See the thing is, I assume you want a well trained copy editor and such, and many copy editors, are good at language, not technology, so they just don't work well with LyTeX or XML or whatever.
Now again... if you are self publishing, do whatever you want. Otherwise if you don't use Word (or something Word compatible) you will be limiting your publishing options significantly. (BTW unless you are self publishing, InDesign is a terrible option... it's a layout program not a writing tool, and many publishers still use Quark, or some other layout tools.)
--- Nothing To See Here ---
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.
http://www.literatureandlatte.com/scrivener.html
Gets some pretty good reviews, and targeted specifically at writers of long texts. Includes chapter management and version control.
Have only used it briefly - but liked it.
I've written "Growing Better Software" (go grab yourself a free* copy). At first I thought LaTeX would be the way to go, as I was pretty sure I'd need to provide my finished result as PDF. I didn't want to spend a lot of time fiddling with layout, but focus on writing- and this is exactly what LaTeX promises.
I found LaTeX gives you a very convenient way to separate chapters; you can simply have one main file and include the several chapters in there.
However, I found the learning curve rather steep- books are rather complex documents, so there's a LOT to learn before you know all the nooks and crannies. And so, every time I wanted to do something near-trivial, I had to look it up (no, I didn't start by ploughing through a several hundred page manual first- I wanted to focus on writing, after all). Also, I found myself spending too much time correcting syntax errors in my markup, rather than actually writing- I found that worse, in fact, than needing to 'fiddle with the layout'.
I got so tired of doing things in LaTex' convoluted ways that I switched to OpenOffice halfway the project. It worked like a dream- I simply set the page/paragraph/chapter layouts and finally could focus on actually writing. As it turned out, I spent less time fiddling with the layout than previously in LaTex. Having used Word before on 300+ page functional documentation, I also found OpenOffice to be much more stable than Word. Indices, page references etc. were a breeze, as was creating the PDF.
Perhaps the book doesn't look as good as a professionally typeset document- judge for yourself. In any case, for my particular purpose, OO.o worked better for me than LaTeX. Perhaps you need to write a lot of math formulas, in which case LaTeX may suit your specific situation better.
* as in beer- conditions apply.
Visit http://ringbreak.dnd.utwente.nl/~mrjb/growingbettersoftware to download your free copy of the book
Just use latex. It does everything you need.
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.
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
Id start by asking your publisher, they will know what format they will want. If they don't have any recommendations, then I would stick to something standard, that's good for writing long text.
Word and OpenOffice are both out. While they are fine tools, they are really designed for smaller documents.
Framemaker is a good tool, and is industry standard. It will cost though. Last I checked it worked on linux, mac and windows, although that was a long time ago.
You could take the plain text route, and use either latex or docbook. Both are good, and both are reasonable standards.
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).
DocBook sounds like you could benefit from it a lot. It's a standardized XML namespace (http://www.docbook.org/) which allows you to use the more popular XSLT stylesheets. AND you can put a customization layer on top of that should you want.
You'll typically transform from XML to TeX and then to any of the 98234098409234 other formats that tex can be exported into.
Git, Emacs, LaTeX and Linux.
Do you even lift?
These aren't the 'roids you're looking for.
I've used LaTeX (specifically TeXShop) lately for my latest books ( Translucent Databases , Disappearing Cryptography , and Policing Online Games . It does a remarkably good job with handling equations and it's easy to understand --- if you think like a programmer. You can just insert macro codes whenever you feel and you can also redefine the markup language whenever it strikes your fancy.
That being said, it takes some time to understand because errors in one section can trigger error messages in very different places. You need to think like a programmer to find them.
I've also used CVS to store the various versions of the document. LaTeX uses pure text files and so most of the features of CVS/SVN cross over.
I can say that I've used InDesign and come away impressed. You may also consider using MS Word because the copy editors and others who work with you on the project will probably insist that it's the only word processor that they know how to use. Sigh.
"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.
Schroedinger's Brexit: The UK is both in and out of the EU at the same time!
I edited a book on business and legal issues in game development. 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!
Brian "Psychochild" Green
MMO developer's blog
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.
I wrote instruction manuals for a previous employer, for about a year. During that time I used WordPerfect and Word. I very quickly learned to avoid Word (plenty of unpredictable bugs),and learned to love WP's (only one bug that I found, and it was 100% predictable) "Show code" function. Since I was doing writing and layout at the same time, I wouldn't have survived without it. The ability to examine everything the program sees and change it at will was an incredible problem-solver.
Mind you, those were the days of Windows 95... Things may have changed since then.
I can think of only one alternative to using MS Word, other than WordPerfect or OpenOffice: use a text editor. That way you can concentrate on the text when writing. When you are done with that you can use eg Scribus (a DTP programme) to do the chapter layout, or let someone at the publisher worry about it.
First, my books:
Animating with Blender
and
The Essential Blender
The last one usually hangs around #1 seller on Amazon's 3d Graphics section, so you can judge my authority on that I guess.
I've worked with several technical publishers (Wiley/Sybex, Focal, No Starch, APress) as both an author and an editor, and at all of them, the manuscript pipeline has been MS Word. I've used OpenOffice, which has worked fine. Some publishers use the change tracking and notes features, some do edits with comments right in the text (weird but true).
As an author, you don't have to be concerned with generating a ToC or an actual Index. Keeping a running list of nice index terms is to your advantage, though. So really, if you're running a modern OS and have a word processor, and ftp client and an email package, you're set up. There really aren't any surprises.
Other than one other poster here who commented on how freaking much time it takes. They're correct. I was writing books over the last two holiday seasons, and my publisher wanted me to work on one this year, but I figured my family would officially kick me out if I tried for three in a row.
If this is your first time, get some feedback early on (first few chapters) from your editor. Ask them to be completely honest. I know some editors will tend to baby you a bit, but personally if I've written something that blows, I'd rather hear it bluntly.
Ask them to send you a properly formatted sample chapter from someone else's manuscript so you can be sure you're using their style guide correctly.
-W. Richard Stevens, author of 7 popular technical books. [R.I.P.]
I'm about to finish my fourth book for O'Reilly, Beautiful Teams: Inspiring and Cautionary Tales from Veteran Team Leaders (which should be out in stores by March).
As far as tools go, my coauthor, Jenny, and I wrote our first book using Microsoft Word, but could just as easily have been using OpenOffice, Pages or any other word processor. One thing that was enormously useful was EndNote for managing the bibliography. Our next two books were in O'Reilly's Head First series (PMP and C#), and we wrote them entirely in Adobe InDesign. (People think that there's a whole team of people designing and laying out Head First books -- it was just us, our editor, and an awesome but overworked graphic designer, Lou, who helped improve our layouts once we had them in reasonable shape.) InDesign isn't exactly the easiest tool for a book author, but it was sufficient. But it made me really appreciate word processors!
A few things that really became clear to me over the course of working on these books:
a) Pay attention to what you're delivering to your editor, and what they'll do with it. Publishers have their own set of templates and production stuff to get camera-ready copy together. Head First was a very interesting lesson in that, because Jenny and I actually produced a lot of camera-ready copy ourselves. But for most books, whatever you turn over to your publisher will get transmogrified into their own internal format.
b) The production editor people I've worked with and talked to (not just at O'Reilly, but at other publishers, too) have been extremely competent, and it's their job to take whatever it is you give them and make it work. It needs to be copyedited, typeset, and reviewed, and sent to a printer. I highly recommend getting to know them, and being as flexible and agreeable as possible (they generally won't ask you to compromise your vision for the book -- it's generally about technical stuff, like how to deal with footnotes, references, images, etc.)
c) You asked about version control. One of the best authors I've ever worked with, Karl Fogel -- he's a contributor to Beautiful Teams, and also just a great guy -- wrote a fantastic book called Producing Open Source Software, which you can buy from O'Reilly or download for free from the website. (Anyone who's interested in starting or contributing to an open source project absolutely needs to read that book. Disclosure: I was a technical reviewer for it.) In true open source fashion, Karl made his version control repository for the book available, and that's a good model to copy. Jenny and I didn't do anything quite so formalized; we just shared folders, and that was sufficient for us (even with hundreds and hundreds of image files for each Head First book).
d) This is the most important thing: make sure you have a clear idea of what it is you want to write! It's easy to get started on a project, only to have it trail off because you don't really have a whole book's worth of material. The more you can outline, the more research you do, and the more you prepare, the better the book will be.
Now, that's all assuming that you have a publisher lined up and a contract signed. If you don't, I highly recommend reading through the excellent Writing for O'Reilly section on their website. They walk you through all of the steps of proposing a book and the mechanics of actually working with a publisher -- and from everyone I've talked to, it's very similar
Building Better Software
The most important consideration is the format desired by your publisher. If your publisher wants doc files, you get to use Word.
Any publisher's staff is overworked and underpaid, just like the rest of us. If you make your editor work harder because you won't work to the company's requirements, then they won't work as hard on your book. You want them improving your book, believe me. You don't write as well as you think you do. Nobody does.
Will the publisher try to work with you when you present your manuscript in a bastardized mix of LaTeX and POD? Sure. But you won't make friends. And being friends with your publisher's employees is essential if you want your book to actually appear on bookstore shelves.
Textmaker, Oo, LaTeX, Adobe, for the big picture, yes. But none of those are adequate for the smaller scales. Try ZuluPad by Tom GERSIC to keep your minutae all in one file and organised. http://gersic.com/zulupad/ Nothing else I have found bridges the gap so well between the neccessary artificial hierarchical framework we require to grasp complex things, and the actual nodular homogeny so inherant in real life. I use this app for expository prose but I'm sure it would be adequate for even, fiction. I have seen the truth, and it makes no sense
I tend to keep things simple. I wrote Implementing CIFS in very plain HTML. Yes, by hand. No, I didn't flail myself with birch bows or kneel on jacks just to prove my inner strength. It was honestly the simplest, easiest way to format everything. Mind you, I had a very supportive publisher.
...and I used to write college papers in Runoff, so I'm used to that kind of markup.
...and I would probably want to learn Docbook if I were to do it all over again.
Plus not thinking too much, which it sounds like you are doing. I usually carry a notebook and pen with me everywhere and write whenever I can, then I transcribe my work into Open Office's word processor. For a book like you're writing, my outline would basically be the chapter-by-chapter synopsis most publishers will likely want from you.
A feathere, from ye leftmost winge of a plump female goose. Fie, begone from mine pelousse, thou insolent knayve!
-- I Newton
Confucius say, "Find worm in apple - bad. Find half a worm - worse."
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.
I've used Word since version 1.0 when it came with a mouse in the box. I've written three 300+ page books with it as well as dozens of lesser works (RFPs, manuals, etc.) using every version except 2007. (I stalled on 2003.) It is NOT TRUE that Word 'doesn't work' for longer documents. Although its foibles are greatly exaggerated, it's also NOT TRUE that Word has zero problems. I like the way it generates TofC and indexes, but in my book before last I discovered if you want to do more than one index, it flat out won't work even though you know technically how to change the code to do it.
The real issue is that a word processor should stay out of your way and be as invisible as possible. You want to concentrate on writing the content rather than paying constant attention to the word processor itself. If it takes a great deal of time to figure out how to do something new, then that is time wasted and not spent on content. In that sense what you are familar with will slow you down less. It's like deciding to use a Dvorak keyboard instead of Qwerty for a new project. Sure, Dvorak is more efficient. How much time do you have to unlearn the first and memorize the second? My fingers do the walking and they walk all over qwerty without me thinking about it at all. Same issue applies.
How about a moderation of -1 pedantic.
I write technical content for a living, so I ought to be exactly the kind of person who can answer your question. Alas, no. In fact, there may not be a simple answer!
The crucial thing with technical content (especially manuals, which is most of what I write, but also techie books) is that it gets revised and repurposed a lot. So "the right tool" needs to support structured content, which cuts down on the human effort of revision and repurposing. And all the "best" writing tools that support structured content use XML. (Or SGML, which is almost the same thing.)
But here's the problem with XML: you need a lot of infrastructure to support it. Unless you're willing to be your own XML software hacker (and a lot of writers are) that makes XML out of reach for a freelance tech author.
(Hell, it puts XML out of reach for most writers of any kind. Most companies that produce a lot of technical content still use very old-fashioned non-structured tools. Investing in all that infrastructure is too scary for most managers. It costs them in the long run, but how many business decisions have anything to do with the long run?)
So what's the alternative? Stop worrying about tools. Or at least no more than you really want to. If you're willing to become an XML nerd, then fine, download all the OSS XML tools that are available, and start training yourself. But if you just want to sit down and start writing, you should just use whatever tools you're most comfortable with.
And that can be Word. It's not PC to say so, but Word (or any other common word processor) is perfectly capable of doing a well-structured document. It just takes more discipline on the part of the writer. That means you don't do a lot of low-level formatting, even though word processor GUIs tend to encourage it. Use a styles, not low-level formatting, to indicate things like section breaks, bullet lists, and computer output. Word processors usually have obvious buttons for doing this, but they almost always use low-level formatting (begin indented paragraph with bullet type 3) not styles (item paragraph).
It can also be LaTex. You'll get lots of people telling you that LaTex is your only choice. Not true. It has its advantages if you need to to finely tweak the presentation of things like equations and charts. But for most content, you should only use LaTex if it's the format you're most comfortable with.
But more important than the specific tool is structure. Together with structure. And don't forget structure. A maintainable technical document is as carefully structured as maintainable source code. Good writing tools make it easier to write well structured documents, just as good programming tools make it easier to write well structured code. But in both cases, the writer or programmer is ultimately responsible for creating and enforcing the structure.
about what I have learned so far.
First, I assume you are working with other people on this. My current project, http://nostarch.com/xen.htm has two authors, along with a tech editor, a regular editor, and all the other people the publisher handles.
First, do not use a non-text format to store your book while you are still working on it. Sure, all modern GUIs have merge facilities and change tracking, but the tools are extremely clumsy compared to even the most basic text revision control system. Do not underestimate the power of diff.
Second, when dealing in text, write your rough drafts in mediawiki markup (unless you are super-familiar with Latex or the like) - it is simple, and it gives you a nice output format for dealing with rough drafts. Heck, it means that if you are working with editors that need a gui, they have one.
The idea is that everyone can use text (or wikis.) once you have the book done, you can get copyedit to put it in whatever format they like (or alternately, you can write a sed script to convert the basic mediawiki to basic latex or whatever) the basic idea is to separate the 'write the book' task from the 'format the book' task.
How about Mercurial (hg). For my personal projects it beats the heck out of subversion...
Censorship is obscene. Patriotism is bigotry. Faith is a vice. Slashdot 2.0 sucks.
I wrote a 250 page tech book with Writer.
The publicer wanted all material from me in Word format. They sent all their templates in Word format as well.
It was few years ago, and I really did not want to use MS Word, because I've lost some stuff with weird Word crashes long time ago. Word must be a lot more stable these days, but back then it wasn't.
The tool is not the most important thing to worry about. The writing will take a lot time, I ended up writing to 3 am at night for several weeks. The last week before the final deadline was so bad, I slept one hour or so per night. At the morning of the deadline I slept from 6 am to 7 am, and saw a horrible dream in which rats were eating another rats. It was the worst nightmare of my life, which describes the state I was in.
It was a very good experience, I'm happy to have a book written by me in my bookself, and few thousand sold to others. Just prepare for the hours this will take! Tell your wife/girlfriend that for next 6 months you'll be extremely busy.
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).
As a professional writer for decades, I have used most of the tools.
Word is a good place to start, but you will want to move off of it quickly for big projects. A key point that has not been covered enough is the distinction between writing and printing. Word is a reasonable writing tool, but a bad printing tool for large documents.
Most big organizations with an in-house technical publications department use some sort of SGML or XML tool. FrameMaker and AuthorIt are popular. Flare is gaining ground, but I have not used it so I can't say anything about it.
FrameMaker is very good for giving complete control of documentation layout (docbook) and is able to export to PDF or web. In general you don't want to be too tied down to how text is presented while you are writing it.
If you must use Word, try to get the template sorted out early on and disable formatting changes. Word can quickly get out of control and you have dozens of almost identical formats in a document.
To boil years of experience down to a few tips:
- write as simply as you can and don't show off
- try to be consistent
- write what your audience needs and can handle
- use the active voice
- use graphics and tables instead of wordy paragraphs
- find as many examples of bad writing as you can and study them intently to really understand why they are bad.
Writing a tech book is a great experience. I wrote one for O'Reilly (Big Book of Apple Hacks) and here's what I discovered:
It's hard. Particularly at the beginning. It isn't like writing a series of blog posts. But it also (like everything else) gets easier the more time you spend doing it. By the time you're done the later stuff will seem easy but you'll be wishing you had time to rewrite the early stuff.
You can crank it out in a few hours a night but try to get a whole week or weekend to work on it when you're first starting out. You won't make much progress but you'll learn what not to do.
Don't be afraid of Google Docs. While the editors will want stuff in some certain format if you have contributors Google Docs seems to be the go to choice.
No matter how many "free" copies you get, it won't be enough. Everyone will want one.
Six months after publication you'll be looking stuff up in the book you wrote.
oo.org has everything on your list except I'm not sure about any VCS stuff.
Sure a lot of people here will try to scare you into selling your soul to Word, but it needn't be so. If a publisher can't deal with pdf at least... well you could try to self publish if you're not worried about up front money. Seems you'd get more of the profits too. lulu.com is one self publishing house that seems good.
I've written three technical books, one of which is now going into its third edition, for three different academic publishers. Points I have learned:
1. Publishers don't want you to format your book. That's their job. They want to receive double-spaced plain text, left-justified, with each figure in a separate file and a note in the text where each figure is to be inserted. (The figure captions are typically inserted at the end of the text.) Fancy things like Word cross-references, automatic footnote formating, etc. cause publishers great pain and are to be avoided.
2. MS Word works just fine for writing books. (I also wrote my Ph.D. dissertation in Word.) The only revision control I did was write each chapter as a separate file, and include a date code in the filename (so that I could go back to earlier drafts when needed). Each publisher with which I have dealt has sent me a required template; each of them was in Word. Needless to say, follow your publisher's template!
3. Figures are by far the biggest PITA in book writing and publishing. I ended up in each case sending the publisher pdf files. Get explicit instructions from your publisher about figures before you start (they will usually instruct you about their format preferences).
4. Keep your ms copies in several different media. After you've spent several hundred hours on the ms, the thought of a hard drive crash begins to weigh on your mind.
5. Don't worry about index generation. The publisher does that (via a contractor, usually); but feel free to edit the result.
To be honest, the most useful tool I've used writing books is a simple spreadsheet. It has three columns: a date column, counting down to the date I am contractually obligated to deliver the text; a page completed column, with the total number of pages written by the given date; and a pages per day column, which calculates, based on the date and pages written, how many pages I have to write per day in order to finish. (A rule of thumb is to have 500 manuscript pages for an academic book.) As others have commented, it's too easy not to write one day, then another, and then a week, and then you can't meet your deadline (at least with material to which you're happy seeing your name attached). The spreadsheet was my way of keeping the nose to the grindstone -- if I took time off, I had to write 2.1 pages per day to finish, then 2.2, then 3 ... but if I wrote 4 pages per day for a week or two, it would go down. It's a motivational tool.
Suff you don't know to ask about: The biggest things one should know about academic writing relate to the business of publishing:
1. GET AN ATTORNEY. The contract the publisher will send you is, of course, biased in the publisher's favor. My attorney requested changes in my first contract -- all of which were accepted by the publisher without any comment at all -- that more than paid for his fee (by several times). He also included clauses that protected me from several problems of which I hadn't thought (like, what happens if the publisher accepts your manuscript but never publishes it? Or, what do I get paid if the book is published in new media, like video or a new electronic format?) GET AN ATTORNEY.
2. Never, ever forget that your relationship with the publisher is a business relationship, not a personal one. This can be easy to forget when dealing with your editor, with whom you will have to work closely for an extended period of time. Authors have forgotten this rule at their peril: Ask Eric Weisstein. GET AN ATTORNEY.
3. Others have written about advances. I don't know anyone who gets an advance for an academic book. You get paid based on sales, after the publisher has paid everyone and everything else. Because of this, consider writing the book so that it is suitable for schools (universities, etc.). All that's required in this case is just some exercises in the back of each chap
I'm currently using a slightly-macrofied LaTeX to write a full length book on Scala (it also has a pre-processor to handle syntax highlighting), and I must say that I couldn't be happier with the toolset. LaTeX is extremely clean and easy to use, especially once you've been working with it for some time. The publisher is extremely happy also, since it means that all they have to do to get a printable copy is just run pdflatex.
Interestingly enough, the publisher gave me my choice of tools. Word was suggested, but they jumped at the chance when I offered to do it in LaTeX. I'm not entirely sure why DocBook is so popular, considering that it really doesn't do much that LaTeX doesn't/can't. As I said, I couldn't be happier with the tools I'm using.
As for versioning, I'm using Git locally and SVN upstream (on the publisher's server). This works out really nicely since I can commit like a madman without slowing down or breaking my train of thought. At the end of the day, when I'm reading to show something to my editor, a simple "git svn dcommit" is sufficient to push my commits globally. This of course takes some time, but it can be done separately from the writing process. Don't underestimate the value of instantaneous commits!
I can't imagine trying to do a book in Word. Or, more precisely, I try *not* to imagine. I know a lot of publishers like it, but I only see it as an inhibitor of the creative process.
What everyone else said about the publisher is correct, but some are more flexible than others. When we wrote the _bash Cookbook_ we started out using an O'Reilly wiki that was a great idea but the implementation wasn't there yet, so we switched. They wanted us to use MS Word (they have templates and macros and other tools), but graciously allowed us to use OpenOffice.org v2 when we pushed back about Word (one of us had no Windows machines).
So we used OO.o v2 with 1 file per chapter and a Subversion repo. At the time, v2 was bad at doing includes, so the code examples were in-line and later extracted into files. (Backwards, but it mostly worked.) ODT was great since we could unzip and grep it for stuff when things move (constantly). Try that with Word! (Or, don't.) I don't know if v3 is better at dealing with styles with includes. Otherwise, OO.o did everything we needed, including a "master document" (MS used to call them binders I think) to tie all the chapter files together in the right order and provide a unified ToC and index. We also generated review PDFs from that.
However, during the final copy-editing they turned the files into Word, which did introduce some errors, hard as we all tried to find and correct them. :-( I don't know where it went from Word. They used to use FrameMaker but I'm not clear if they used it for us.
I loved working with O'Reilly and plan to do so again in the future. Great folks.
My only other advice is to learn how to use styles and then use them consistently. Don't go overboard with them either, the template on the O'Reilly site is a good start. If you are consistent, then one way or another you can export into some other format if needed (e.g., unzip and parse XML for ODT, macros for Word, whatever).
Good luck!
-JP Vossen (co-author _bash Cookbook_).
LaTeX with the associated tools (BibTex, makeindex, etc.) worked very well for a textbook that I coauthored. It was also the publishers prefered format, although they sent our LaTeX source out to a commercial type setter who proceeded to mangle the mathematics in unimaginable ways. Who knew that when an integral ends in "dx", the "d" and the "x" should be on the same line?
I can see the sense in using a basic text editor to begin. I like that too.
At the present, though, I have a headache while drafting a piece which can hardly avoid a few math/tech symbols. My usual text editors don't participate in a standard for math and technical symbols.
After a few experiments in dumping various wp outputs to .RTF, and then retrieving/re-editing from .RTF --- it's seldom that the symbols are preserved. I'm trying to use as few different ones as possible, but I can't even identify a small few that are treated in a standard way. This is starting to drive me crazy.
-wb-
I wrote three Linux books (one of which was reviewed here on /.) plus two Computer Based Training CDs. Though the last one was released about 6 years ago, I have a few thoughts for you that I hope are helpful.
Back when I did my first book, there wasn't much other than Word. I wound up writing most of it in vi. It sucked for me writing it and for my publisher to turn it into something that was ready to be published. For my second book, I had a collaborator and we wound up doing most of the work in Word since there weren't many adequate tools for Linux. We had one file per chapter and used the revisions to track what each of us did. The third book (and the two CBTs I did) followed that, though I think I did use what is now OpenOffice to write some and then save it in .doc format. The .doc format was the only format my publisher accepted that I wanted to use - I could have used TeX, but chose not to. In those cases, I did use CVS, but only to store the changing binary versions of files. I seem to recall that in every case, I could just send my publisher a list of words I wanted in the index and they'd build it for me.
If I were to write a new book, I'd do it in DocBook/XML. It's really great at abstracting presentation from content, and tools like OpenOffice can export as DocBook for you. Check with your publisher and see if they'll take it. If you're interested, there's a lot of useful information on DocBook in the LDP Author Guide, which I started writing years ago.
I think the important things aren't the tools, but more how you approach writing. You'll be doing this over a long period of time and you'll have to write a lot of pages. You need to be really disciplined to write N pages per day so that you don't get behind the curve and realize that you need to write 50 pages in the next two days before it's due.
I took care of this in a similar way that I write code. I started by listing the chapters I wanted to do, which was part of the proposal. I then started breaking down each chapter into smaller and smaller sections until I knew what I wanted to put in each paragraph, then start writing paragraphs. It really helps you focus on a few things instead of having to work on an entire chapter at once.
Good luck with your book.
(a pencil and eraser work well too)
In the end, it comes down to what you put on the page - how you get it there is entirely up to you. You could argue that the publisher wants you to send your text in Word format, but that does not mean you need to work in Word to write.
Tools offer excuses to shift the blame for missing due dates, avoiding the work of writing, and make it easy to find distractions as you discover what all those shiny knobs do.
I go old-school first (pencil and paper) and switch to Word once I have enough content. I don't use any formatting in Word, doing that much later on, freeing me to focus on the task of writing.
I did a book on contract for BMW. I started with Word, but didn't like Equation 3.0 for equations. The results look good, but too slow for a tech book. I didn't want to use Tex (done that, too slow for a long book on a schedule). I ended up using StarOffice, but today I'd use OpenOffice. The equation formatting is pretty fast. The figures you can create inside are a bit too simplistic for a tech book, but on par with Word.
Oh, something else. You don't have life while you're writing. I borrowed a travel trailer from my in-laws and rented space in a trailer park. I put the computer in there and went back and forth from work to the trailer until the book was done. It's a lonely existence. After a while, I knew the radio schedules by heart and that's about all I knew of life in the outside world.
1. Write your book in "DocBook/XML" (or HTML 5 if you prefer).
2. Use the wonderful OpenSource tool-chains to process to PDF, HTML, Kindle-format, etc.
3. Publish yourself via the many, many, print-on-demand services available on-line.
4. Profit?
Seriously, check-out this site for example: http://featherandquill.com/
and
http://www.sajafutura.us/index.html
Over-the-top Response Guy! Giving "Over-the-Top Responses" since 1970.
I've written for several publishers. All but one (O'Reilly) use MS Word, and have custom templates. Some work interchangeably with OOo Writer. Others present problems. Keep your publisher informed. I say that I need to use OOo Writer to have credibility with the community, so they're sympathetic. Test a chapter. Make sure to test all the templates you need to use in that chapter. Be prepared for funkiness. Some publishers use embedded comments, which leads to funky looking labels in OOo Writer.
Hey man.
I wrote Perl 6 Now for APress and boy what a trip that was. There are too many stories to recant. Very briefly though... I wrote the book in POD (Perl's doc format) as it was a Perl book, that's what I know, and it let me easily build tools to extract the code examples and test them, and it let me work in vi. Editor wars aside, I can't use other editors. My fingers fly for the escape key. I wrote a tool by hand -- you're welcome to it, just email me (scott@slowass.net) that compiled POD to RTF for Microsoft Word, which they wanted. There are other tools, but mine faked having written the document using their style sheet, something no other tool seemed to offer. But then I guess style sheets never "take" in MSWord, so someone had a job, for every book written, of manually re-applying styles to each and every sentence, heading, etc, etc. No wonder no other tools applied styles! They don't stay done in MSWord.
I started with Strunk & White's Element s of Style and it saved me from really looking like an ass but I discovered, painfully, that I still couldn't write. It's a skill as valid as programming or any other skill, and it's one that, even if you're born with aptitude for, you're not born with the skills of. Take time to learn to write. I rewrite each chapter several times. The copy editor seemed to sub things out and files would come back having been edited by MSWords with default languages for various countries. Digging around the in the RTF guts this is clearly visible but just using MSWord, I don't think it is. The person working in the Netherlands had an interesting take on style versus the other guys and gals.
APress was awesome. They let me weigh in on absolutely everything -- cover text, image, page count, price, etc. I wanted a small book but ran high in page count. They wanted a higher page count so they could charge more. I refused and edited myself violently. They edited me more for content than volume. It felt more like a collaboration than a ploughshare.
Late editing -- copyedit -- in MSWord sucked. The document turned into a mess of green and red stuff crossed out. ORA has more progressive methods for editing I'm told. But you're probably stuck with your publisher for your first book at least. You have the right idea -- it's a long process, and it's worth tooling up for.
Show your book to as many people as you can in the industry before you turn anything in. Higher Order Perl was written under peer review, with perhaps hundreds of people commenting on the chapters. Unless you are a god, you'll find that you fall into the same tired old traps, getting history wrong (writing a populist rather than correct version), mangling technology, and so on. It's hard for a book to raise to be more than one man's knowledge but if the book is to be worth its pulp, you must do it. Even Knuth heavily relied on his readership for corrections and completeness.
Test your code examples.
Get your book done on time and work your ass off to do it but still plan on taking a few extra months to deal with fall out from tech review. Don't go longer or the expense associated with your book will raise to the point where you publisher will be further in the red than they wanted.
This is something I really regretted not doing -- whore your book out when you're done. I'm pretty introverted and used that as an excuse, but if you don't tour around the country a bit and speak at user groups, you will regret it. Blog about it. Comment on other people's blogs. Keep sending out review copies until a review appears on Slashdot and other places. Talk to people you send review copies to. Send review copies to user groups. Without too much pressure, help guide them into submitting reviews. Most places won't run badly written, uninspired reviews. That's a good thing.
Good luck!
-scott
After nine books, I've learned: Write the text, create the illustrations and diagrams, and stop worrying about how to format it. You're not going to have much control over that anyway (that's up to the publisher). On the other hand, if you're planning on pre-publishing your own work in draft, for feedback (and publicity), you will need to worry about formatting, appearance, layout, consistency, etc. Personally, my approach is to do my next book rough-draft as a blog (http://perfect-computer.blogspot.com; only a couple of weeks old). That keeps me focused on the ideas and concepts, and not on the exact wording, nor the formatting. Then, when I think I've said what I want to say, I'll assemble it all into a manuscript for publication. It's easier to get a contract that way, 'cause you can show "samples" of your work. Frankly, you can waste so much of your time on the publishing details you can lose enthusiasm for your work. Write. Write longhand, if you must, but Write. Let the publisher worry about the forms and formats.
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.
"Stein on Writing" by Sol Stein
http://www.amazon.com/Stein-Writing-Successful-Techniques-Strategies/dp/0312254210/, is the only other weapon-of-choice against mundane writing.
Here's the demo for Scrivener ...see just how different the Way of Working with words, it is...
http://www.literatureandlatte.com/Scrivener_intro.mov...
Sheer Capability...
You can't go wrong with latex. It is routinely used to publish 200+ page page Ph.D. theses.
This is slightly ranting so keep that in mind.
I have written a couple of "how to" books for work. Each have been slightly less than 250 pages long. The company had Word installed on the computer I was to use and I found it "adequate" for the task.
However that are a few "gotchas" to expect when running ANY Microsoft product and Word is no exception. It decides where to put any inline graphics. You can then re-position them where you want them (most of the time) but every fifth time or so you load Word it will "forget" these setting and once again put the graphics where it wants them, particularly if one is near a page break.
While I have not used anything else on a project this big (I am not normally an author) I found the constant "babying" of Word necessary to get it to do what I want instead of what IT wants to be very emotionally draining.
I agree about the copy editing. This is a discipline all of its own. My wife has just completed a 2 year course (in 12 months) to qualify as an editor. There is a 'language' to the editing marks that leaves me somewhat stumped, but is obvious to those in the know.
I also heard her say, on a regular basis through the course, that they are taught to "edit without changing the writer's voice".
So, if you are editing your own work, be careful that you edit in your own voice. (I recently wrote (most of) a 50,000 word novel for the National Novel Writing Month and found myself editing on the fly and in some cases editing out good dialogue and making it 'wooden'. Then, I recalled my wife's words, and the words flowed much better in my own 'voice'.)
OpenOffice.org is what I used.
Looking at space, radio, science and computing from a 'down-under' amateur enthusiast perspective.
I wrote a book back in 2000. I asked the publisher if I could use LaTeX, and the publisher said "Sure, no problem!"
Well, it turned out said publisher didn't know LaTeX from a hole in the head, so after I'd written a few chapters, I discovered I had to do format-conversion so their evil MS-Word-based toolchain could digest my work.
They completely messed up my formatting; it was a nightmare from beginning to end.
If I ever write another book, it'll either be self-published or done in collaboration with a publisher willing to use *nix tools.
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.
Well, it doesn't sound like you picked the wrong publisher as you weren't using the correct tool.
Every publisher I know has a whole style sheet and a Word template that tells you exactly how to do all your formatting. And if you get the formatting write in there, then they aren't going to convert it to anything and all your formatting would stay intact. By "load text into word" do you mean you sending were them a .txt file?
The style guides tend to be very clear on what you can and can't do about formatting, and it's really not worth trying to outthink them as that'll mess up the later production process like you saw here.
Unless they were so out of it that they actually didn't tell you anything about how you were supposed to send your stuff in advance, in which case, yes, avoid them like the plague :)!
My video compression blog
Word isn't designed for book publishing, but it is the format that publishers are most comfortable in receiving material in. They are going to reformat it anyway, so the important part is getting the text to them in a comprehensible format.
Framemaker and Quark are publishing tools and likely as not one of these is going to be what the publisher is going to use in the end. Choose wrong, and you will have a mess because these are not easily convertable to each other. That is why Word works - the publisher is used to converting Word to whatever it is they are using.
Using any tool the publisher isn't familiar with is going to result in the text not coming out with the content you intended. That means either your work will not be published at all or it will be retyped with errors. You will not catch all of them. This is a disaster.
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.
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 have written this http://www.eyrolles.com/Informatique/Livre/bsd-9782212114638 book, and the following tools were used:
vi for edition for DocBookXML files
aspell for spell checking
CVS for version control
Canvas (that one is not free software) for pictures
DB2LaTeX for transform DocBookXML to LaTeX
teTeX to perform page layout and produce output files
I just got done writing and self publishing my first book titled "Program Phases, A Programming Language and API Translator". The book is designed to help programmers learn new programming languages quickly.
I edited the book using Word XP 2002. The way Word renders formatted text is really inconsistent. Fonts changing randomly was really annoying. A page will not render properly unless a print preview is first displayed. I used Adobe Acrobat to convert the word files into a PDF. Acrobat worked really well.
I recommend first determining the page size and margins that are required by your publisher/printer. Create a test chapter and convert to PDF. Try different tools and see what works for you. I did create a small test using OpenOffice and I may use that for my next book.
My book's web site is located here: programphases.com
i have a friend who's a professional story writer for film -- to keep track of all the plots and sub-plots -- he makes (for example) three rows of coloured posty notes -- one for each plot along a timeline that extends the width of the wall -- this is the master overview for everything that goes on in the 2hrs -- it works better than anything he's used on a computer.
i have another friend, who's a renaissance scholar - she independently uses, and swears by the same method for when she's writing her books.
2cents
Mind mapping tools would accomplish much of what you mention. I can vouch for FreeMind. It's a Java app, so it's comfortable in many locations - Windows, Linux, Solaris, OS X. The import, linking, embedding, and export functions are simple to use and reasonably robust.
My workflow with FreeMind goes something like this:
1. Brainstorming session (lots of 'input' key, and copying/pasting from all my open resources)
2. Organization and linking from node to node
3. Export to some intermediary format (Options abound)
4. Work in editor - pure or WYSIWY*. (I really enjoy TeXmacs for all the wrong reasons - the exported TeX seems to be awful)
5. Check in or otherwise maintain revisions (rsync, anyone?)
The beauty of maintaining an open scaffolding is that it's easier to digest and/or massage later.
I can say from semi-professional experience, that working in Microsoft DTP products (Word, Publisher, FrontPage) is effectively binding the work to that product forever. To craft a document in Word, using the tools provided that make such a piece of software worthwhile (indexing, TOC, pagination, revision tracking) tie a document so inextricably to that software that the content is effectively under lock and key until additional exports can be made (albeit losing access to those key features, though I can't say how OO.o writer handles revision imports).
All that said, maintaining some alternative document base, in an agnostic markup language is highly beneficial.
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
I had to use MS Word for a project because it was selected as a "standard" because everyone has it, and it has features like change tracking, and so on. I'd guess it increased the amount of work I had to do by about 30% compared to, say, writing in DocBook.
Save copies of everything, because it's very easy for multiple "standard" and "compatible" editors for MS Word files to garble things horribly.
For reviews, PDFs plus markup seem to be pretty usable. I've not found an editor that everyone can live with. I am personally quite fond of DocBook, and it's my first choice by far. If you have to use a more common application, FrameMaker is horrible and sucky... But *anything* beats MS Word.
My blog: http://www.seebs.net/log/ --- My iPhone/iPad app: http://www.seebs.net/seebsfrac/
for keeping track of all the ideas and bits of informatation.
journler
Cool! It is marvelous to see so many published Slashdotters offering hard-won observations and experiences. That makes me feel very proud!
--I've been in this racket pretty much forever, and I only have one cautionary note to offer. . .
Try not to fall into the trap of substituting, "Serious Preparation," for actual work. It's easy to spin away vital energy talking about the project rather than actually doing the project. Reap the rewards when the job is done; I've seen many a promising idea fail to materialize because of this. I've been guilty of it myself more than once, and it's a horrible thing; like miscarrying. --Are you seriously asking what kind of word-processor to use before getting down to work? How many weeks do you plan to blow on that kind of nonsense? You'll start in the New Year, will you? Sure. Just keep telling yourself that until it's time to find a new excuse to avoid jumping into the Void.
Cut it out, silly! Books have been written on napkins, for goodness sake!
Though, to your benefit, it sounds rather as though your project is less a dream than it is a, "Things To Do", which suggests to me that you've already secured a contract. If that's the case then, Good For You! That's no small feat. --And if you've already accepted some money, then you will have by now met your two new best friends and motivational coaches; Deadline Stress and Abject Fear! (This is good thing; I know how hard it can be to get out of bed in the morning to hit the desk without that extra friendly push.)
Beyond that, I will say this: Good luck! You CAN do it! --But ONLY if you get to WORK!
I hope everybody here is pulling for you! Writing a book is a very special and demanding personal challenge and you will need lots of moral support over the coming months. Consider it given. I love writers!
-FL
I've not written a book but I support two authors. #1 has always written in a word processor, so I have left him alone to do that. He is on OO on Linux. He does not do any elaborate formatting on account of not knowing how. The only constraints I imposed were, one document per chapter, no one document over 100 pages - split it into two or more files, no inserted graphics - graphics as standalone files with labels and tags where they are to go. It has worked fine, the publishers accept his stuff with no problems, and while OO has crashed once or twice, he has never lost any data. This is in years, it goes back to OO V1. Charts and illustrations are done in OO also. When he has to give presentations, he does them in Impress and then exports them as pdf, and all venues have been able to show them perfectly with no problems. He tries to get collaborative submissions to shared author publications submitted in rtf, because of problems with heavily formatted different versions of Word.
#2 was writing in OO, and it was fine for short documents, but on his first book got heavily into formatting, to the point where on a tight deadline he was spending all his time trying to get the format to look right, and his ability to do that was very limited (like, using spaces instead of tabs!). It was getting very upsetting. I took a deep breath and moved him to Lyx one weekend - took all the writing so far off into plain text, and then cut and pasted it back in myself and reformatted it so all the headers and subsections worked OK. After an afternoon showing him how to navigate and do the different headers and so on, he never looked back and would never use anything else. It felt very brave at the time, but it worked brilliantly. You can export from Lyx into text of course, and the publisher is fine with that, and when he has to supply print ready copy, as sometimes happens, he can just deliver a pdf.
What I learned is, the tool is not so critical as long as (1) the user can manage it (2) he does not try to do page layout, but leaves that to the publisher. Also that some form of outliner (what #2 is using Lyx for) is very powerful once people get it.
My belief, but its the belief of an outsider, is that what they really should be using is a multiple view tabbed text editor like Kate, on a 22 inch or higher screen. I think that with that, they'd be much better able to control content, double views into the document would make it easy to do cross references and comparisons of material, there would be just about no formatting other than what they put into a header - like 'Chapter 1: xxxxxx'. Subsections can be done similarly. Search and replace is very powerful. When I've mentioned it, they are basically sympathetic, when shown, they see how it could help. But the issue is, no-one really wants to learn a new way of working if the old one works to a reasonable extent.
If you're writing a book about Unix, shell commands of that general form are not uncommon. Certainly going back to my marked copy of the published book, some backticks have been changed to single quotes, wholly changing the meaning of the text (there's an instance on page 198, for example). Certainly there are publishers who are able to set up processes that correctly preserve information from author's finger to printed page while allowing copy-editors and layout folks to do their thing, and I concede it's possible that some of those publishers use Word, but MCP wasn't able to do that in this case.
ITYM "get the formatting right". It was not formatting that was the problem. Formatting the pages is not the author's sole responsibility anyway, there are folks at the publisher who work on page styling and who - let's face it - probably have better judgment on that than authors. It was the content that was screwed up. Backticks and quotes don't just look different, they are different characters. Yes, I believe I sent them a text file, they had internal markup standards for indicating which sections of the text should be in a monospace font, and so forth. From the evidence left behind in my working directory, it looks like I used latex2x to automate that.
Back in 2000, I wrote the Apache Pocket Reference and mod_perl Pocket Reference in DocBook SGML using emacs, with a perl script to convert to LaTeX for me to be able to preview what I had written. This year I updated the former book as the Apache 2 Pocket Reference. This time it is written in DocBook XML - again using emacs. Each of the 400-odd directives is held in a separate XML file and I have scripts that parse those files and the directive definitions in the Apache source code and report on inconsistencies. I also published two vegetarian cookery books written by my wife. These were written in LaTeX - with each recipe being held in a separate file. Writing a book is akin to a complex project. Keeping each section of the book separate and maintained in a version control system means that you can see which parts of the book are changing and do quick word searches just by using grep. Emacs also has various tags functions that allow searching and replacing across tagged files, so even managing a book split into almost 500 source files is quite easy.
I've written two books and found that Word works very well. Remember, It's not just you. There are the technical editor(s) and the publisher's editors, who concentrate on grammar and usage. They've got to send you comments and the highlighting and commenting features of Word are very good. That plus the track changes feature make figuring out if you've applied the suggestions pretty easy. The styles features also works well and most importantly the publishers know them and can work with them. Anything that's a picture is usually delivered separately, at least to my publishers.
If you are doing research for your book on the web, Zotero, http://www.zotero.org/ is a free Firefox extension that is sort of like bookmarks on steroids. It's really handy for organizing and
making notes on stuff you will need to make reference to again.
As for editors, what do they do exactly?
IANAL but write like a drunk one.
...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.
Sorry, guys, but to me these seem like choices for people who are techies first and last and writers only incidentally. There are tools out there that were designed for writing complex documents *without* needing to bloody well learn tech skills. Personally, I'm quite fond of Quark CopyDesk, which was designed for professional writers who want to explicitly be able to block out formatting stuff and just focus on the words. Let's also remember some of the useful orphans out there like Nisus. These days you can get copies for ten or twenty bucks, including everything, and the feature set is rich as the dickens. Of course, I do most of my writing in TextEdit, which replaced BBedit for me, and do the rest in Indesign so YMMV.
It's all about the information. And what we do with it.
I used Vim and LaTeX. The listings package allows you to reference an external source code file (either the whole thing, or selected lines) and insert it with nice syntax highlighting. Beautiful output and very easy to use.
I am TheRaven on Soylent News
It seems nobody wrote about source code formating or referencing. I've used latex with the listings package with great results.
You can actually point to your source code and it will be formated, framed, highlighted... No copy&paste errors, non-compiling code, typos.
If you go for latex check kyle (KDE) or texniccenter on Windows.
I've written a really big technical document (>200 page dissertation) in FrameMaker and various smaller ones in Word, LaTeX, and OpenOffice. Since I was a student at the time, Frame was merely expensive, not insanely expensive. And it did a good job. It has a sane document model that can, for example, keep captions with their figures (unlike Word). But it's in no way free and pretty darned expensive. And it doesn't play well with version control.
I dislike writing anything bigger than a page or two in Word, and despise writing anything in it of any length that contains figures. I once wrote a technical paper in Word that had over 20 figures. Then I went and edited some of the text. Suddenly, many captions were no longer with their figures, and some of the figures overlapped each other. (This was extra fun when a large figure covered a smaller one. Where did Figure 18 go? Guess what? It could be hidden under any other Figure.) I've also had bad experiences with Word cross-references just suddenly becoming wrong and having to correct them manually.
If you're willing to put in some learning time, LaTeX is an excellent technical documentation tool. It is fairly novice-hostile (moreso than Emacs, IMHO), but extremely expert-friendly. There are decent tutorials on- and off-line, and front ends like LyX that make it easier. And it plays really nicely with version control.
Whenever I have a choice, I use LaTeX for docs more than a few pages long. (For short ones I use OpenOffice and/or Emacs to write HTML.)
Cool, that sounds good. I started using some of the DocBook XSLT scripts to do just that, but I needed some weird behavior for some of the imported listings - e.g., I only needed to show lines 10-20 of a particular listing - and ended up rolling my own.
The Army reading list
LyX gives you all the capability of LaTeX without having to learn a new mark-up language.
If you use Word, you can expect to have captions separated from figures, cross-references wrong, figures with a changed aspect ratio, and layout changing half way through the manuscript for no apparent reason . . . and the final result will look as if it was typeset by an amateur.
If you use LyX, you can have a professional-looking PDF without even trying, along with figures and equations that look like you intended them to. You will also have a source file which will still be accessible in ten years time, on any operating system. Can Microsoft guarantee you will still be able to read today's format into the indefinite future?
I have written many documents using LyX, mainly internal technical reports and proposals, many of them hundreds of pages long, with hundreds of figures, and estimate using LyX rather than Word reduces my writing time by about 50%.
If a book makes it to print (dead tree edition) then someone, usually the editor, has determined that a minimum number of people would like to not only read the book but purchase it as well. This is a difficult task as evidenced by the many books you can find in the clearance section of Half Price Books and other stores that buy the many remainder books publishers were unable to sell at the asking price. In other words, editors have the ability to risk the publisher's money and the health of the publishing company! They are not proof-readers as many people expect.
We have always been at war with Eurasia!
Oh, I completely agree that my name is very associated with my books. If you knew my name, you'd agree. My point is that any noob will screw up copy editing, layout and all the other facets of publishing, when compared with the output of someone who does only each one of these specialties for a living.
This is especially true for material that you've already written yourself. Nobody can do a good job copy editing his own work, or laying out his own book. Look at your bookshelf and I think you'll agree that it's easy to identify the books designed and laid out by the author. One needs independence from the author to do those tasks well.
I do completely and absolutely agree, however, that one must review the work of these specialists with a microscope when the proofs are returned to you, the author, for approval. I have sent text back three and four times until it is exactly the way I want, and that includes the style and substance of the index. Note that in this phase of publication the author is editing the work of the other specialists. That do-but-have-others-verify process is critial to the production of a high-quality text, but it is the author -- and only the author -- who gives the final approval for printing of the galley proofs. It is the author's responsibility to ensure that they are as he wishes them to be for, as you state, it's his name most closely tied to the book. Because he has the final approval (as well as approval at several intermediate steps, like copy editing), the author is in control over what is associated with his name.
One of the contract clauses my attorney inserted into my first contract covered the case of a published text that differed from the galley proof. That clause has never been exercised, for the books alsways have been exactly as I have approved them -- errors and all.
It has been my experience that the difference between "academic" publishers and "technical" publishers, at least as far as their treatment of authors, is zero. I've had technical publishers that were total slimes; one told me that there were many other authors he could get to write the book he wanted on his terms, so there's at least one that wasn't trying for a long-term relationship. (I haven't seen the book in print yet...) My best relationship is, in fact, with an academic publisher; they are constantly pestering me to write another book for them, contrary to your assertion. I think one's relationship with a publisher is an ergodic, independent random variable.
Regardless of whether one's publisher is considered academic or technical, however, I still say that one lives at one's peril in the publishing world without an attorney. One can think one is "cooperating on a project," but never forget that publishing is first and foremost a business.
I ended up using MS Word for the ugly monkey book, because O'Reilly only offered me that or LaTex, and I didn't want the hassle of figuring out the latter, which I'd never used. It worked out okay; I just used their template, and made a point of religiously applying the styles they'd set up. And yeah, I kept copies of the Word files (one per chapter) in revision control, though I don't think I ever used that for anything other than backup purposes.
The biggest lesson I gained from it was that while outlining and proposing a book is exciting, and getting it accepted by the publisher was really exciting, actually writing the thing was way more work than I'd expected. I'd written and edited professionally for years in the magazine business, so the writing part was familiar, but the difference between a 3,000-word article and a 500-page book turned out to be much bigger in practice than it had looked in theory. Especially late in the process, when it was all about plowing through everything again to get it all to the highest possible standard, the book was a huge undertaking.
It didn't sell particularly well, which was a disappointment, but the fact that I had believed (and continue to believe) in the book's premise made it possible for me to invest the work required. And in hindsight, I think of the book as a success, at least for me personally. Not because it sold a lot of copies, but because the process of writing it taught me more about its subject matter than I could have learned any other way.
I never would have finished it if I hadn't been sustained by my naive hopes of big sales, and I'm glad I wrote it, so I guess I'm glad I was naive. Presumably you have high hopes for your own book. That's great. Hang onto those. They will be essential as you close in on completion, and the mountain of remaining work just seems to reach higher and higher.
Good luck!
Science writer Olivia Judson has a post about tools for organizing the source materials for an article. I'd like to know what she writes the actual article with.
Here's her biographical blurb from the NY Times: Olivia Judson, an evolutionary biologist, is the author of "Dr. Tatiana's Sex Advice to All Creation: The Definitive Guide to the Evolutionary Biology of Sex," which was made into a three-part television program. Ms. Judson has been a reporter for The Economist and has written for a number of other publications, including Nature, The Financial Times, The Atlantic and Natural History. She is a research fellow in biology at Imperial College London.
Hes an anti-ms troll asking other anti-ms trolls for help. Good choice I say.
Not much help, but fwiw, I use Word (I like the spell/grammar checking, mostly), but then I write stories, not code. It is then imported into pagemaker, combined with illustrations, fonts and such, and then exported to acrobat files that the printers use. --Ray
http://www.beanleafpress.com
Hmm. I'm quite sure that Word was capable of doing the above at least as far back as Word '97, when going from .doc to .doc. Sometimes "Smart Quotes" had to be fiddled with to make sure it didn't get autocorrected as it was typed, but that was pretty easy to do. Certainly the Mac made it pretty easy to insert any character in a font like that; I hadnt used WinWord much back then.
My book was a few years later than that, but I definitely used Word and defintely had some text formatting complexities that went fine in the workflow. For example, in video Y' means luma, but Y with a closed single quote doesn't mean anything.
Perhaps your publishers were running some kind of autocorrect macro that messed things up or something (which would be a fine argument for your "never work with them again" plan the second time it happened).
But I don't think Word itself was the problem.
My video compression blog
Agree fully 100%. The take of the good feedback here is to focus on the creation on the content and leave the formatting to the publisher.
Now, while nobody have mentioned it here, there are tools to help you to develop your ideas and create that structured content. As some people said, linear writing, focusing on all the details from the first pass is not the way to go. You should develop your ideas as they come (top-down and down-to-top, as they emerge). If you know the main structure that you are going to have, your write top-down. If you have a lot of ideas, you capture them and then organize them in groups until you have a logical structure and order.
In addition, depending on the size of your document, a work processor only shows a very small portion of your document - about 0.25% of the document for a 200 pages document. You have to do a lot of scroll-up/down. Its almost like I like watching a paint thru a pinhole.
Mindmapping tools solve both problems. They let you capture your ideas and structuring (and restructuring) as you write using drag and drop. Can also see the whole document in a single screen or expland the sections (or the text) to see the details. While oriented to the educational market, Inspiration has the best tutorial to explain the concept here: http://www.inspiration.com/videos/Inspiration . It explain how to develope your concept (and content) and then export to MS Word using Styles instead of formatting (as other advise here). Inspiration is very good, but not the most polished and capable application in the bunch.
The most polished mindmapping application that I have seen so far is Mindjet's MindManager ( http://www.mindjet.com/ ). I saw the demo on version 8 and it is impressive (worth the money). I have also used version 7 for a few months for developing ideas and writing procedures. The exports to MS Word look even better than the ones from Inspiration. And you can even add due dates to the content sections (for your own control) and add attribued like completion percentage. You can also embeed graphics, Excel tables, attachments, links, etc. It also has and outline view, so that you can sort the order of topics, etc.
The free alternative is FreeMind (http://freemind.sourceforge.net/wiki/index.php/Main_Page ). The lastest version have many extensions for exporting in different formats too. I develop my personal mindmaps in FreeMind and keep a portable version of FreeMind (with Java) in my pen drive. FreeMind exports to OpenOffice format, but you could use OpenOffice for converting into MS Word, if required.
So the steps are:
1. Forget the document formatting applications mentioned by 99% of the commenters here.
2. Use a mindmap application to create your content.
3. Export to MS Word.
4. Send to you publisher and let them take care of the rest.
Easy, isn't it?
I just self published by uploading my lyx generated pdf to booksurge. You can see what it looks like -- Amazon will publish images of the text in a week or so through their "search inside the book" program. Look for "Dorothy's Oz Dream: a Guide to Enchantment and Empowerment." Good luck.
... is the result of the faulty assumption by people who use tools like Word and Framemaker, etc., that their small scale toys are scalable to real needs of publishing. The reality is that one of the very few tools that can (so far) handle documents of indefinite size, is LaTeX/ConTeXt. Publishers provide the class and bst files, the lazy bums who want to be authors invest a day or so learning it (unless you write complicated documents with lots of line-broken equations, tikz type graphics, etc., it should not take a person of average intelligence more than about 1-2 hours to learn the way to do things). There is absolutely nothing, not Endnote, not anything else, that beats the robustness, ease, simplicity and elegance of the BibTeX system.
But we have commercial companies who obviously have a vested interest in continuing the popular myth of GUI-dependent authoring tools. And mentally incurious people who continue to make life hard for the rest of us because of their personal delusions / laziness.
Different publishers...different requirements. That said, I worked with 3 other authors on a book published last year by No Starch Press and we used Open Office (NeoOffice on the Mac) to write the text and generally PNGs for images. The publisher was happy with this and it served our purposes nicely. Using word processing software that would run on each author's preferred workstation made collaboration simple. We submitted text in Open Documment format. This worked great for us.
I wrote a book using OpenOffice, and I don't recommend doing so yourself.
I like OpenOffice a LOT, but it has little annoyances and printing bugs which add up to problems. These can cost you weeks of issues.
And when you have these issues, your publisher is unlikely to be able to support you in it.
That said, it's hard to hate a program which allows you to write perl scripts which unzip a file, make a modification, and re-zip it. This makes some very sophisticated search and replaces or style cloning possible.
Lastly, without having done it myself, I'd agree with people who recommend LaTex. Not because it does a wonderful job, but because you as a writer will be VASTLY more productive. If you have a wisiwyg editor, you'll be forever messing around with how things look. With a LaTeX post-processing system, you can write in a powerful editor and not spend a large percentage of your time poking at styles and pagination, etc.
At the end, you either like what LaTex gives you or you don't. You can edit the formatting styles, and make changes systematically throughout the document without making this page an exception and that page an exception. That really seems IDEAL.
I've already paid the price of doing one book. I have the methods down. So my next book will probably be OpenOffice again. But if you haven't started yet, write it in LaTeX. You can always port it to OpenOffice later, if you want to use that for your ultimate output because you can't get LaTex to look the way you want, but you can't go in the other direction and you'll be MUCH more productive using LaTeX.
A commissioning editor takes something you wrote, and tells you if it hits their target market, and how to change your writing to fit their market better.
A copy editor takes something which you understood when you wrote it, and turns it into something others can understand when they read it.
Both are essential in creating high quality work.
Blessed are the pessimists, for they have made backups.
I wrote a book in LyX and would do the same again. LyX's structured environment saved me many hours of formatting and cross-referencing. There is also no other way that I know of to get the same quality of output. My publisher uses Word for copy editing (many publishers do, apparently for no good reason), but it was a fairly small matter to convert the manuscript.
Word is good because when it comes time to show your book to other people and get them to submit in-document comments/changes, you'll find that no one else has Adobe Professional or other software packages, but everyone has Word. Also, Word is pretty easy to use for the average writer. Once the text is complete it's easy to move to another program if you want a fancier layout.
It's designed for novel-writing, but very flexible for any writer's workflow. It is made for writers of voluminous volumes, and it may be what you're looking for. Try the demo. It is adaptable to just about any workflow, or any type of lengthy work.
Also, all of it's product is separate RTF files accessible from any other app. It took me a long time to find the right tool for long work. I tried everything available, assiduously, over a period of months.
LSBXE met my requirements and more. The author is responsive to feature requests/bug reports. The only outstanding issue is it supports Unicode, but can't yet handle the upper range of Opentype fonts, such as the Vista standard fonts (Candara, Calibri, Consolas, etc.). So it can be tricky if you must use a lot of math/logic characters in those particular fonts. Anything else is fine. This is an aesthetic bug, pretty much, because those symbols will work in unicode fonts.
But those fonts are very beautiful.
Anyway, yes, please try LSBXE if you are interested in writing long work.
I notice no one has mentioned scrivner It's not really for writing your final draft but is great for organizing ideas and gathering information. Once you have the basic layout you can export it to text documents and work on the final draft in something like Adobe Indesign. It only took me a hour to learn with its built in tutorial. I found it a must in my writing (mac only though sorry).
I just started as an editor at No Starch Press. The company is already set up for LaTeX and Subversion, and we're introducing git.
Seriously, check-out this site for example: http://featherandquill.com/ and http://www.sajafutura.us/index.html
Seriously, stop being a tool and surrounding every post in <tt> tags.
Put identity in the browser.
Mindmanager is a very useful tool for brainstorming, blamestorming, knocking together documents, project plans, to do lists, and pretty much anything you need to throw together quickly.
It allows you to throw ideas together, move them around, assign markers and relationships and generally allows you to offload the actual thoughts and information instead of spending time thinking about how many rows you need in a table or in what order it needs to be in.
I've written documents in Word / Open Office Writer / Excel / Project / HTML for years .. and wasted a lot of time and lost a lot of thoughts. If I ever decided, or had to, write a book again this is the tool I would use to start with.
Note that I use mind manager at work every day for just about everything :) There is a free version as well called Freemind.
You have a sick, twisted mind. Please subscribe me to your newsletter.
The OpenOffice info there seems to be out of date -- they have a pretty good OpenOffice.org stylesheet. I wrote my two O'Reilly books ("Fedora Linux" and
"X Power Tools") in OpenOffice.org that way.
OOo is a pretty reasonable choice, especially with a custom stylesheet, because it is XML-based and can be transformed into other formats.
I haven't written a book, but I deal with people who do. In the end, it is really about the words, not the tool. I have seen people write in TextEdit, the transfer to a word processor, then the publisher handles the rest.
Since I am a Mac user, I will put in a good word for Nisus Writer Pro (http://nisus.com/pro) since it handles export to .odt and .doc, which is usually the formats that publishers expect. Scrivener (http://www.literatureandlatte.com/scrivener.html) is also a great tool for gathering ideas and putting your thoughts into outline form.
But really, just concentrate on your writing, and the rest will fall into place.