Slashdot Mirror
Tools & Surprises For a Tech Book Author?
Fubari writes "I have questions for those of you who have written books: what writing tools have you found helpful? I want to start my book off right (so I'm pretty sure I don't want to write it in MS Word). What has and has not worked well for you? So far I have thought of needs like chapter/section management, easy references to figures (charts, diagrams, source code), version control (check in/check out parts like chapters, figures, etc.), and index generation. I would also welcome advice about what I don't know enough to ask about. Did you encounter any surprises that you wish you had known about back when you started out?"
Check out the O'Reilly website:
http://oreilly.com/oreilly/author/ch02.html#tools
If you are dead serious about writing, and don't mind paying for the best tools, Mellel is for you. It is a word processor application geared towards professional & academic writing, and the features are quite convincing. See http://www.redlers.com/mellel.html for more.
InDesign is lousy for anything beyond a few pages. Use InDesign for cover, flap, insert, back cover layout. Adobe Frame Maker is the answer if you want to go Adobe. It was purchased from another company, and thus, very un-adobe like, but it's what most people I know use for tech manuals. I'm a tech writer and we use Word at work. It's not as bad as you think.
I'd recommend www.thepiratebay.org.
There's also TorentReactor too for nice compilations.
Oh wait... you want to MAKE books? Oh, nevermind.
If you have a publisher already lined up, ask them what they want. Most publishers already have copy editing / print production processes in place, and are very specific about what they want from authors (e.g. what formats for images and graphics, templates for your chapters (often Word), and a style guide for writing, how figures should be referenced, etc. You can then use whatever tools you want, provided they deliver what the publisher wants.
If you don't have a publisher lined up, try and keep your materials in generic and easy-to-changes formats, so you can pour them into whatever format your publisher wants.
Remember, production is all about the publisher - it is not about you.
If you are self publishing, there are lots of web-based self-publishing companies - and they too describe what you need to feed them.
I'd have to say that there were a few surprises I learned along the way :)
First, expect it to be another full-time job. It takes up as much time as you have, and even more, and forget about having a personal life while you're writing it. The people I know who've done the best job writing a tech book are those who are independent consultants who have non-billable time or employees where their employer supports their writing a book. The extra time each of those kind of people can get to write during working hours is a huge help.
As far as using Word goes, it works well enough for this stuff. Expect to use a separate file for each chapter. I used a subversion repository to check everything into and out of, just to be safe.
Make writing a habit. Set a production schedule and stick to it -- its too easy to take a day off, which then turns into two days, into a week, and then just gets worse and worse. Set out a plan, both long term and short term, track your progress, update the plan as you go, and keep writing.
Finally, using a continuing example throughout the book might be nice for readers, to give them a continuing context, but it greatly increases the risk of a lot of rework on your part if you change your mind about something halfway through writing. You'll have to go back and re-edit everything that depends on the decision you changed. It does make it nice for the reader but much harder for you.
Good luck! Its a great learning experience, whether you finish the book or not.
-- bab
It sounds like you want LaTeX. It has a built in reference, chapter, figure/table referencing and an ToC system. It is great for equations and a whole host of other things. It does have a learning curve, but it works great. The one problem with it is that it does not have a spell checker. So what you do is type in Word and then copy/paste it into LaTeX for the formating and everything else.
Fly me to the moon Let me sing among those stars Let me see what spring is like On jupiter and mars
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
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)
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.
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.
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/
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.
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.
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
InDesign is lousy for anything beyond a few pages.
It used to be, but it has gotten a lot better in recent years, pulling in much of Framemaker's feature set. It is a viable option these days and for some projects better than Frame.
I'm a tech writer and we use Word at work. It's not as bad as you think.
Did you read his criteria? Word is pretty awful when you try to use it with versioning and it is still pretty terrible for long documents. The continuing document corruption issues for large documents, especially with images makes it a poor choice for almost any long document, IMHO.
I wish I'd known I had chosen the wrong publisher.
I published a book with SAMS (an imprint of Macmillan Computer Publishing, which is not related to the British publisher called Macmillan). I was working with some half a dozen other authors and only needed to complete a couple of chapters (the page production rate that Que require from authors is so huge that I'm sure I could not have achieved that as a sole author, at least not if I wanted to take the time to check the copy I was submitting).
The basic problem was that MCP's editors (I guess copy editors initially) loaded the text I gave them into Microsoft Word (I assume, I can't remember if they confirmed this). It immediately "corrected" all the punctuation. Since the book was about Unix, there was an abundance of single and double quotes, backticks, and so forth. They all got totally screwed up. On proof reading, I spotted these, fixed them and sent the corrected text back. Then of course they loaded the text into Word again and broke everything a second time.
The whole experience was frustrating and I was left with an author credit on a portion of a book that was riddled with stupid errors. I am embarrassed to have been associated with such a farce of an attempt at a technical book. I will never again work with any publisher in that group.
I should disclose that following publication, I had other difficulties with MCP in that they published the text a second time in another book under their Que imprint, without consulting me or paying me. They rectified that when I complained, though I didn't know to do so until I noticed my text in a book I browsed in a bookshop. So there is some subsequent bad feeling on my part, so take it as read that you're not getting a dispassionate report here. Mind you, the book was published ten years ago this year, so I've calmed down a bit now.
The list of publishers I'd consider collaborating with now is much, much shorter - only about four publishers (plus any others I don't know about - and I'm sure there are many - who will accept camera-ready copy).
"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
-W. Richard Stevens, author of 7 popular technical books. [R.I.P.]
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.
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.
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'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.
You can't go wrong with latex. It is routinely used to publish 200+ page page Ph.D. theses.
I used OpenOffice for my third book (600 pages). It was a big mistake. When I was done, the publisher reminded me that they wanted the output in Word format. I converted the OpenOffice format to Word, and the result was terrible. This is because I tend to use lots of complex layout features, with nested tables, placement of text boxes in the margin, etc. These kinds of layout features are very important for book design today: the most readable and successful technical books have sophisticated layouts, and the publisher will not generally do this part for you.
OpenOffice has improved alot since then (three years ago), but even so, if you are doing a large manuscript, use the tool that the publisher wants. You can't leave layout to them anymore: use their tool and styles, and do your own layout.
By the way, I have used OpenOffice to generate PDF files, and it has many glitches. If you are generating a large manuscript as a PDF, the likelihood that you will run into a glitch or two is high. E.g., their PDF generator does not seem to render properly when images are placed at fixed positions relative to a paragraph. I had problems with that. And for a production PDF, everything must be perfect.
For my most recent book (500 pages), I used Word from the outset, and did the entire layout myself. Word is a terrible tool to use for that, but it worked. I had the layout control I needed, even though it is flaky (text boxes move suddenly if you change anything). There are lots of quirks that make Word unsuitable for a large manuscript, but it can be made to work (with lots of frustration).
I once used Framemaker to do a book (my second book, the 800 page one), and that was a good experience.
Nowadays, I wish I had a tool that allowed me to do wysiwyg layout (very important for a good layout), but that also generated DocBook XML. That way I could publish the content on the web as well. But I don't know of a tool to do that. Even better, it would be nice to have a tool that would maintain the book book as a manuscript (with print layout) and an online wiki....
OpenOffice claims to generate DocBook output, but I tried it and had problems. It was a new feature when I tried it: maybe it works now.
I am not a proponent of using the Latex tools. I must say that I am not very familiar with them, so I am not one to comment. But they seem not to be layout oriented, and as I have said, today the visual layout is very important. A book is no longer a stream of text with pictures interspersed: it is a complex mashup of text and pictures. To create that, you need a layout-centric tool.
- Cliff
Key point: InDesign is for *layout*, not for writing. The design goal of InDesign and similar programs (Quark Xpress, Scribus, etc.) is to allow you to place regions of text and/or images exactly where you want them on the page, to twist them into exotic shapes, to apply fancy colored borders or backgrounds, and generally to take the existing content and make it artistic. I would never use one of these programs to write a book, unless it were something like a magazine where the text is split up into little oddly placed regions, and even then I'd write the text itself in some other program before copying and pasting into the layout editor. (I speak from a few years of experience with InDesign and Scribus, btw)
I have two books, one in its second edition and one in its first. Both have lots of equations. I insisted on using LaTeX and having the books typeset in LaTeX, the publisher agreed, and it's one of the best decisions I've ever made.
Here is why I'm happy: THE EQUATIONS IN THE PAGE PROOFS ARE THE SAME AS THE EQUATIONS IN MY ORIGINAL MANUSCRIPT. I can't tell you how important that is. Most editors and proofreaders do not have a clue about technical material. If you write in Word or some other format that is "rekeyed" by the publisher, I guarantee that by the time you get to page proofs, many of your equations will be unrecognizable, and you will go through hell trying to straighten things out. The publishers insist that they can avoid this problem, but friends who are authors and who did not use LaTeX assure me that the publishers mess things up. In my case, various things were fouled up (graph legends for example were frequently reversed because the graphs had been redrawn), but not the equations.
Lots of folks here are saying to use what the publisher tells you to use, they have a system, etc. I had five publishing houses (three commercial and two university) offer me a contract, and all agreed to produce the book in LaTeX. They just contract out the compositing. this may vary by publisher, but in my case, it was not a big deal. YMMV.
I wrote a book a few years ago.
That was in Office v.X on an old PowerBook (I even started in the original "can't print" beta of Word v.X).
http://www.amazon.com/Compression-Great-Digital-Video-Techniques/dp/157820111X/
And I've got a couple due in 2009 for different publishers, so this has been much on my mind.
Based on a lot of the other comments, people are really focusing on the formatting aspects of the workflow: Latex, FrameMaker and all that. But if you're writing a book for a standard tech publisher, you likely will never even have a direct conversation with whomever does the layout. You turn in structured text and figured to an editor, when then passes it off to layout after editing.
And if it's any kind of a series, they'll be doing formatting according to a well defined template and style that'll map to the styles in the document you give them.
So, the actual workflow is that you get a Word template, and write everything in there. The key thing is to follow the Styles religiously - every paragraph should have one as you type it. Think writing in old school HTML, or XML to someone else's Schema.
Also, try not to even think about formatting; there's no saying what goes on what page based on Page Preview in Word or alternative. If you want a new section, use a section break. This is object-oriented writing, where you're really trying to get the content into the right structure for easy processing later on.
I recommend working in Outline and Normal/Draft mode only, since that's where you see the structure of what you're doing. Personally, I'm a born again believer in outlining. I outline a chapter, and then jump in and write the part of it I'm thinking about at the moment. With the outline there, it's easy to realize I need to introduce a concept earlier in the chapter and then jump there and do a quick sketch of it, since the earlier section already exists in the structure. The act of writing an outline also helps define all the stuff you didn't know you needed to figure out.
But don't be a slave to the outline as it exists; structure can need editing as much as prose. Don't be afraid of moving sections and chapters around as helps you communicate better. That's a lot easier to do early in the process.
My video compression blog
I've now written two books that were published by major New York publishers, co-written another book that was used to launch my publishing company, and published two additional books by somebody else under my publishing company. So, speaking from both sides of the fence, there are a few things that will be handy for you to know...
What you do in part will depend on if you have a publisher already, or if you are writing the book to try to sell to a publisher later. If you've got a publisher already, as has already been said on here, ask your publisher for guidance - they will provide everything you need, and if you have questions, your editor is there to answer them.
If you don't have a publisher, one of the most important things is to realize that you are writing a manuscript, not a typeset and formatted book. This is incredibly important - all-important, in fact. If you hand the publisher something that isn't formatted as a manuscript, when it comes to a lot of publishers, you are essentially shooting yourself in the foot. Formatting the book is their job, not yours.
So, for a manuscript, what is usually going to happen is that an editor is going to read a printed copy, and make lots of notes on it. It must be double-spaced (so that notes can be made between the lines), in an easy-to-read 12-point font. Courier is preferable, but Times New Roman is acceptable too. Page numbers will be on the top right, and your header will be on the top left, with an extra space in the header to make the manuscript easier to read. Each chapter should also begin around the middle of the page.
When it comes to word processing programs, flexibility is key after a certain point, so that you can provide whatever file format is requested. But, when it comes to the writing itself, use something that you enjoy working in, and that you find easy to use. In my case, I use WordPerfect, in large part because once you start typing, it feels like a typewriter, and can also save in just about any format I need.
(It is also extremely powerful, and I use it for typesetting and indexing, but that is beside the point for this discussion.)
One thing that is handy to know regarding images - for an image to print properly, the image must be 600 dpi (dots per inch) - the best type is a high-resolution TIF file.
Indexing is not your problem, but you can make it easier for the publisher. The way you do that is to make a list as you write of important key words, and give that list to your editor for the indexer. That way, whoever indexes the book has a cheat sheet of sorts, and can do most of the index using a find function. Considering that indexing has to be the single most grueling, boring, and tedious job in all of publishing, the indexer will be very thankful for it.
As far as keeping organized goes, not much to say there - keep organized. You're going to be handing a long document over to your editor to be worked on, and your editor should be spending his or her time working with your words, not fighting with the document itself. Take note of where each figure is supposed to go, and be prepared to provide that information.
And I think that covers the tips I'd want to pass on...
Robert B. Marks
Author, Demonsbane in Diablo Archive
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
...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.
Yes, you're right. Tools are wholly secondary to the content.
Good tools make it easier to produce good content. If your tool makes it easy to represent structured content, then you're going to be spending more time thinking about the content and less time thinking about the tool, which is very important when you are writing a lot.
After all, when was the last time you read a book and though "Wow, the page layout in this book *rocks*?".
Very rare. Much more often I think 'this page has line breaks in the wrong place and the kerning is off'. This is because I know a fair amount about typography. Someone who doesn't, just thinks 'this is hard to read,' and most often they will blame it on the content. If you give someone the same text, with good and bad layouts, they will have two, very different, reactions to it.
Reading badly laid-out text makes you feel tired and makes your attention wander. If you don't realise that it's because of the layout, you will just think the book is rubbish. If you are putting your name on the cover, then you want it to be easy to read so that people will be judging your content.
It's just like good user interface design. No one notices good user interfaces, but everyone notices bad ones. The good ones get out of your way, and let you concentrate on the work, the bad ones get in your way and make you think about the UI, not the problem.
I am TheRaven on Soylent News