Forgot your password?
typodupeerror
Books Media

Tools & Surprises For a Tech Book Author? 325

Posted by kdawson
from the chisel-and-clay-tablet dept.
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?"
This discussion has been archived. No new comments can be posted.

Tools & Surprises For a Tech Book Author?

Comments Filter:
  • by Noodles (39504) on Sunday December 21, 2008 @04:50PM (#26193641)

    Check out the O'Reilly website:

    http://oreilly.com/oreilly/author/ch02.html#tools

    • by Cybersonic (7113)

      This is a great reference! Thanks...

  • Mellel (Score:2, Informative)

    by Anonymous Coward

    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.

  • Well. (Score:3, Funny)

    by Creepy Crawler (680178) on Sunday December 21, 2008 @04:54PM (#26193671)

    I'd recommend www.thepiratebay.org [thepiratebay.org].
    There's also TorentReactor [torrentreactor.net] too for nice compilations.

    Oh wait... you want to MAKE books? Oh, nevermind.

  • by Web-o-matic (246295) on Sunday December 21, 2008 @04:54PM (#26193673)

    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.

    • by clintp (5169) on Sunday December 21, 2008 @05:26PM (#26193985)

      I've written (and edited) tech books for major publishers (SAMS, Addison/Wesley, Pearson). I have to agree with the parent: it's not your call.

      While you can write your book in anything you want be prepared to use THEIR tools for going back-and-forth with their copy editors, tech editors, and typesetters.

      If you're comfortable in vi and using markup, that's great. However, don't be surprised when a publisher insists you use a Microsoft Word template and turn on document revision control for your chapter submissions. You may wind up taking your beautiful markup and mashing it into Word before sending it. Your proofs may come back as really awful Adobe Acrobat PDF files that make Foxit crash. Tough. Suck it up.

      Producing ideas and words is your problem. Figuring out how to pass them between multiple people/departments/companies to get a book printed is theirs.

      • don't be surprised when a publisher insists you use a Microsoft Word template and turn on document revision control for your chapter submissions.

        Probably the most insightful comment in the thread. What YOU want to use or what YOU like is irrelevant. It has to be convenient (or at least workable) for the publisher. If it's not, you will be told to make it workable.

        So, which is more work? Writing it in your preferred environment, then transferring/converting it and hoping that it's all there afterwards, or wr

        • by 1u3hr (530656) on Monday December 22, 2008 @12:43AM (#26196971)
          Bear in mind, the publisher will almost certainly NOT want you to do anything with typesetting (fonts, spacing, kerning, etc.). They will do all of that in-house. All they'll want from you is your deathless prose, typed into a pre-set template, or sent to them as raw text.
          Sucks, but there it is.

          I wouldn't say "sucks", but I work on the editing and layout end of the process. Having an author kibitzing on the layout is what sucks. What we need from the author is a functional layout: so we know what level of heading is intended; not "18 point bold Arial".

          I've worked on hundreds of books and I cannot recall ANY authors, including University professors, who had a clue about how to use their tools of choice (as they all had written their manuscripts before bothering to consult the publisher), they all used Word, and most of them like a typewriter. None had a clue what a "style" was or how to use it consistently. You were likely to find paragraphs of body text styled as "Heading 1", reformatted to be 12 point Times. I normally spent half a day cleaning up crap like that before I could export the file out of Word and start the actual layout.

          The ones who did think they knew about layout were even worse though. They try to tell me that "Arial is a great body text", "two spaces are required after a full stop", "underlining is how I want to emphasise", "the text should be at least 14 points to make it easy to read", "my name should be bigger", etc, etc. If you don't know why this kind of thing causes DTP people to grind their teeth, just take my word for it. You do require a degree of stubborn egomania to get a book written and published, but you also have to know when to take advice from people who have more experience.

    • by happyemoticon (543015) on Sunday December 21, 2008 @06:26PM (#26194563) Homepage

      You're also getting at something important: the process of copy editing/production is completely separate from actual writing. While it's entirely possible to just pull up a vi/emacs and write straight Docbook or LaTeX - and I've done it for some documents - I find it tends to have a chilling effect on both my creativity and my attention to content detail if I'm trying to think about content and presentation/formatting at the same time.

      It's the same reason that brainstorming should be a totally separate process from welding your fleshed-out thoughts into professional writing. If you try and force your thoughts to be concise and professional too quickly - unless it's something you're really good at - usually you'll be filtering yourself too much to produce ANYTHING good. If you're thinking about formatting when you're editing the content, your mind is trying to do too much at once and so it does both things badly. Try to do all three at once and you'll probably be horrible at all three. Of course, there are jobs which require you to integrate several processes into one, but integration is itself a wholly separate task, and, again, it should be dealt with separately from each constituent process.

      When I am responsible for the whole thing, from beginning to end, I generally only do one activity (writing a rough draft, editing the draft, and finally formatting it) on any given day, as much as time allows. And if I don't have that luxury, I run around the block or lift weights between tasks to clear my head. This singlemindedness might just be my personal quirks, but I have a job where I wear about fifteen different hats and am constantly pulled in different directions - the kind of job where "strong multitasker" would be in the requirements - and I manage it by organizing my deadlines, planning, and doing one thing at a time. Since I don't believe in multitasking (at least as most people do it - doing ten things in parallel and accomplishing little in any one area), I can't decide if this makes me a great multitasker or a horrible multitasker, but I seem to be doing alright.

      • Re: (Score:3, Insightful)

        While it's entirely possible to just pull up a vi/emacs and write straight Docbook or LaTeX - and I've done it for some documents - I find it tends to have a chilling effect on both my creativity and my attention to content detail if I'm trying to think about content and presentation/formatting at the same time.

        If you are writing DocBook or LaTeX by hand, and are thinking at the samre time about presentation and formatting you are doing it very, very wrong.

  • by bbutton (90403) on Sunday December 21, 2008 @04:55PM (#26193685) Homepage

    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

    • by monk (1958)

      I'll second what bbutton said about scheduling, time, version control and the experience.
      Writing RFID Essentials for O'Reilly was hard but very rewarding, I recommend them as a publisher if you don't already have one.

      If you are working with O'Reilly they will want you to use their style templates from the beginning and will want to work with you section by section. Their templates a few years ago worked best with Word, but OpenOffice support was coming along fast and may be complete now. A books starts with

  • LaTeX (Score:5, Informative)

    by Ironsides (739422) on Sunday December 21, 2008 @04:57PM (#26193697) Homepage Journal
    It sounds like you want LaTeX [latex-project.org]. 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.
    • Re:LaTeX (Score:4, Informative)

      by Sir_Lewk (967686) <sirlewk@gmai l . com> on Sunday December 21, 2008 @05:03PM (#26193767)
      Or you know, just type it with a decent text editor that does the spell checking for you...
    • Re: (Score:3, Informative)

      by bedonnant (958404)
      latex + aspell maybe?
    • Re: (Score:2, Informative)

      by routerl (976394)
      Check out the LaTeX editor [latexeditor.org]. It includes many conveniences, like spell check, thesaurus, word wrapping, etc.
    • Re:LaTeX (Score:5, Informative)

      by jrothwell97 (968062) <jonathan@notroswTOKYOell.com minus city> on Sunday December 21, 2008 @05:13PM (#26193863) Homepage Journal
      Yeah, maybe LaTeX, but use a better front-end, like http://lyx.org/ [lyx.org]LyX. Then you can apply the formatting as you type.
    • Re:LaTeX (Score:4, Interesting)

      by jcarkeys (925469) on Sunday December 21, 2008 @05:13PM (#26193873) Homepage
      Over break I've been learning LaTeX and certainly it's going to be everything a burgeoning author needs.

      I've also been learning LyX and it's a WYSIWYM(ean) front-end for LaTeX. I suggest you try it.

    • Re: (Score:3, Informative)

      by cab15625 (710956)

      There may be better tools out there if you have a big budget, but I'd have to agree. I got sick of word and its quirks when writing my thesis (sort of a technical book if you want to think of it like that). Emacs and LaTeX were a life-saving combination. Bibtex took some getting used to for the indexing, but that was the hardest thing to learn.

      Formatting is easy. Large projects are easy. It copes with all the major image formats. And if using a text editor is not your thing, there are pseudo-wysiwyg g

    • LaTeX + make (Score:4, Informative)

      by sugarmotor (621907) on Sunday December 21, 2008 @05:42PM (#26194147) Homepage

      Use latex and a Makefile.

      Set up targets for every chapter separately; add features / other make targets as you go along.

      Stephan

    • Re: (Score:2, Interesting)

      by Anonymous Coward

      The absence of a spellchecker is the smallest problem with latex. Spellchecking can be done by your favorite text editor (man vim) or external tools such as ispell/aspell. Depending on what you want to do "customization" can come with an extremely steep learning curve (sometimes as steep as running straight into a wall of solid rock):

      - use of custom fonts is tricky for the beginner and even the advanced user usually won't try.

      - exotic page layouts (i.e. everything latex doesn't "naturally" provide such als

    • Re: (Score:3, Interesting)

      by pngwen (72492)

      Most serious academic work is done in LaTeX. My papers are all typeset in LaTeX. I use emacs to do it. The software is free (in all sense of the word), and the documentation is plentiful.

      ispell will spell check it. You can run that in emacs as well, or just invoke from the command line "ispell -t". You can draw figures in any graphics program, export to eps, and then include them in your document. Tables, math, text, sections, all beautifully laid out for you.

      So come on, join us Tex heads! As for the

    • Re:LaTeX (Score:4, Informative)

      by Simon80 (874052) on Sunday December 21, 2008 @05:51PM (#26194237)
      You can learn LaTeX easily with http://en.wikibooks.org/wiki/LaTeX [wikibooks.org]
      • I found the Kopka and Daly book very very useful. Maybe there are newer books for LaTeX 3e, but I found it a great resource.

    • Re: (Score:3, Informative)

      by James Youngman (3732)

      So what you do is type in Word and then copy/paste it into LaTeX for the formating and everything else.

      [Blink.]

      No, don't do that. Just use ispell -t for spell-checking, or edit your text with Emacs.

    • Re: (Score:3, Informative)

      by James Youngman (3732)

      One minor point about LaTeX; it's a language, so if you are a programmer, expect to get sidetracked on issues of making it do exactly what you want, for no good reason other than the fact that for a programmer, that's fun. I know that when drafting my first book (that one was never published) I spent too much time crafting a spanner to put in the margin to indicate that that paragraph needed further work. Getting the spanner to face in opposite directions depending on whether it was on an even or odd pag

    • Re:LaTeX (Score:5, Informative)

      by gringer (252588) on Sunday December 21, 2008 @06:06PM (#26194389)

      emacs, latex, auctex, flyspell -- wonderful combination. Oh, and you'll probably want git/svn for revision control (as suggested previously). There's also a latexdiff program floating around that can put changebars into your output file.

      Flyspell allows you to have the wavy line spellchecker functionality that is fairly common now. It distinguishes between non-dictionary words that appear only once and non-dictionary words that appear more than once.

      No makefile is necessary if you're using auctex. It's just C-c c for latex, bibtex, latex, latex, (pre)view.

      The makeidx package allows you to create indexes (e.g. \index{ancestry!genomic}).

      Yes, it's a learning curve, and the best way to start with emacs/latex is to work off some already written latex files, but the results that come out the other end are worth that effort.

  • Just remember to.. (Score:5, Insightful)

    by contra_mundi (1362297) on Sunday December 21, 2008 @05:01PM (#26193743)
    Save often!
  • by taustin (171655) on Sunday December 21, 2008 @05:10PM (#26193837) Homepage Journal

    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.

    • No, most of them used ink.
    • Re: (Score:2, Interesting)

      by laymusic (140088)

      On the other hand, the first novel submitted as a typewritten manuscript was "Huckleberry Finn", so not everybody who thinks about new writing technology is a bad writer.

    • by djupedal (584558)

      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.

      Yeah, publishers love that...especially with bad handwriting.

  • by Zontar The Mindless (9002) <{moc.liamg} {ta} {ofni.hsifcitsalp}> on Sunday December 21, 2008 @05:11PM (#26193845)

    ...God created DocBook [docbook.org] and Subversion [red-bean.com].

    We use DocBook and SVN to author/edit/maintain the MySQL Manual and related documentation.

    Most of us working on the MySQL docs team also use oXygenXML [oxygenxml.com] for editing - it's neither libre nor gratis, but it's not terribly expensive, and it works well on any platform with decent Java support (one of the few Java GUI apps I've seen that really works, and works well). Handles many common XML formats including DocBook, XHTML, DITA, and TEI. You can also supply your own DTDs/schemas for custom XML formats. Includes both code and visual editing views, as well as instant validation and a built-in Subversion client. Easy to produce HTML or PDF output from XML source. Also has some nice XQuery and XSLT tools if you need them.

  • by Dutch Gun (899105) on Sunday December 21, 2008 @05:14PM (#26193879)

    ...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.

  • Tools for writing (Score:4, Interesting)

    by Tom Easton (1436447) on Sunday December 21, 2008 @05:15PM (#26193897)
    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/ [sff.net]
  • 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 writ

  • OO works just fine (Score:5, Interesting)

    by nikolag (467418) on Sunday December 21, 2008 @05:26PM (#26193983)

    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.

  • 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 ed

  • by paddbear (200274) on Sunday December 21, 2008 @05:37PM (#26194099) Homepage

    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.

    • Re: (Score:2, Informative)

      by Tom Easton (1436447)
      Well, no, your publisher will NOT tell you what word processor to use. At least, in almost 40 years of writing books for publishers like McGraw-Hill, I've never had one do that. Content is the important thing. All else is format, and they handle that routinely.
    • by N7DR (536428)
      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.

      Yep. I was astounded when I did a book for O'Reilly, and they said "Don't use TeX; we don't have anyone here who understands it any more. Use Word with a template we'll send you". Personally, I hated using Word, but it's what they wanted; and part of your job as an author is to make things easy for t

  • 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- boo
  • by Anonymous Coward

    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 req

  • 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 eithe

  • 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).

    • by DaveV1.0 (203135)

      Did you write your part of the book using Word, or did you use some FLOSS?

      • Honestly, after all this time I can't remember the details, but looking at the directory containing the source, I wrote the initial draft in LaTeX. However, it looks like I pushed it through ltx2x; I don't recall whether I gave SAMS the LaTeX, the ASCII or both.

  • I've used LaTeX (specifically TeXShop) lately for my latest books ( Translucent Databases [wayner.org], Disappearing Cryptography [wayner.org] , and Policing Online Games [wayner.org]. 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

  • by PolygamousRanchKid (1290638) on Sunday December 21, 2008 @05:53PM (#26194259)

    "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.

  • by Psychochild (64124) <psychochild@COFF ... m minus caffeine> on Sunday December 21, 2008 @05:54PM (#26194277) Homepage

    I edited a book on business and legal issues in game development [psychochild.org]. Not exactly a tech tome, but I'm a programmer by training, so I hope I can share some insight.

    The important thing, as others have mentioned, is a question on if you have a publisher, if you are going to look for a publisher, or if you want to self-publish.

    If you are going to self-publish, take a long, hard look at what you're doing. Does this have to be in book format? Or, would setting up a convenient website be better? There's a certain cachet to having a published book, but for a lot of tech things I'd prefer to have an online reference. Even if you do have a compelling reason to put the work into dead tree format, having a companion website is highly advised.

    If you have a publisher or want to find a publisher, I'd recommend doing that first. When my co-editor and I thought about our book, we wrote up a Table of Contents for the book and pitched that to the publisher. We went to a publisher of other books on the game industry and they were really receptive to our idea. If you're going to write the book on your own, you might want to write up a chapter in addition as you approach publishers.

    Once you find a publisher, they'll give you the information you need. They might want everything submitted in Word format, as ours did. Use the tools they recommend to ease the process. The last thing you want is an irate publisher, trust me on this one.

    Finally, work with an editor. If you're self-publishing, get an editor! Another pair of eyes with the ability to go through your work with bloody red pen is absolutely vital to ensure that you aren't writing boring crap. If you're working with a publisher, try to get on good terms with your editor from the start and build some respect both ways. The editor's job is to improve your work, so understand that every nugget that is created by your keyboard isn't always made of gold. Your editor is vital to the long-term success of your work.

    Here are some lessons I learned along the way:

    * It takes a lot of time. More than you probably think right now. Even though I was "only" an editor (ha!) for chapters contributed by others, it was a full-time job and then some. Expect to write every waking moment you're not doing something to ensure your survival (eating, sleeping, earning money). Do whatever you can to stay focused, because it's going to take a lot of work, and a lot of times it will be boring. Re-writing a chapter for the fourth time in so many weeks because it just doesn't seem to want to come together defines "test of endurance".

    * Don't expect to get rich. Some people get into writing a book thinking it's the path to riches; it's not. A book that does well sells a few thousand copies. But, as one person put it, a book is an awesome business card. ;) Use the book to open doors and provide other opportunities for you that can help you achieve your goals.

    * It really is awesome to have a published book with your name on it. It's a tremendous sense of accomplishment to have your book sitting on your bookshelf.

    Hope that helps a bit. Good luck with your work!

  • Scrivener (Score:3, Informative)

    by Tom (822) on Sunday December 21, 2008 @05:58PM (#26194309) Homepage Journal

    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.

  • by Rick Richardson (87058) on Sunday December 21, 2008 @06:07PM (#26194399) Homepage
    "The last line of a right hand page should not end with a hyphen. This has been a style rule for many years, yet it is amazing that most word processors do not do this! I just smile when I pick up a book produced with something like Frame and you immediately find these errors. Needless to say, troff does this correctly, and has for 20+ years. A friend commented to me that normal evolution would have gone Word to Frame to troff, but instead, the computer industry has gone the other way!"

    -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 [amazon.com] (which should be out in stores by March).

    As far as tools go, my coauthor, Jenny, and I wrote our first book [stellman-greene.com] 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 [endnote.com] for managing the bibliography. Our next two books were in O'Reilly's Head First series (PMP [headfirstlabs.com] and C# [headfirstlabs.com]), and we wrote them en

  • 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 ma

  • A feather (Score:3, Funny)

    by Hognoxious (631665) on Sunday December 21, 2008 @06:28PM (#26194585) Homepage Journal

    A feathere, from ye leftmost winge of a plump female goose. Fie, begone from mine pelousse, thou insolent knayve!

    -- I Newton

  • 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

  • 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 conte

    • Yes, you're right. Tools are wholly secondary to the content.

      After all, when was the last time you read a book and though "Wow, the page layout in this book *rocks*?". Good technical books have a well-thought-out structure, have something vital to say, and explain their material clearly. It's the content, not the tools. Every hour spent tweaking that TeX macro (or fighting with the word processor, etc.) is an hour you should have spent thinking about structure of the the book, the text, or the (ofte

      • by fm6 (162816)

        Yes, you're right. Tools are wholly secondary to the content.

        That's not at all what I said. Good do tools make the job easier, and the less unnecessary work you do have to do, the more attention you can spare to write better content. So tools do matter. I'm only warning against giving too much priority to finding "the right tools".

        After all, when was the last time you read a book and though "Wow, the page layout in this book *rocks*?". Good technical books have a well-thought-out structure, have something vital to say, and explain their material clearly. It's the content, not the tools. Every hour spent tweaking that TeX macro (or fighting with the word processor, etc.) is an hour you should have spent thinking about structure of the the book, the text, or the (often forgotten) intended reader.

        That's true, but unfortunately some warfare with your tools is unavoidable. As I said before, most word processors are not well designed for technical writing. But using a word processor you're comfortable with may have less martial overhea

      • Re: (Score:3, Insightful)

        by TheRaven64 (641858)

        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

  • How about Mercurial (hg) [selenic.com]. For my personal projects it beats the heck out of subversion...

  • 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 con
  • 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 h

  • 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 fo

  • OpenOffice.org (Score:3, Interesting)

    by Roblimo (357) Works for SourceForge on Sunday December 21, 2008 @10:07PM (#26196113) Homepage Journal

    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.

  • by rmcd (53236) * on Monday December 22, 2008 @01:07AM (#26197093)

    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/ [amazon.com]

    And I've got a couple due in 2009 for different publishers, so this has been much on my mind.

    Based on a lot of the other comments, people are really focusing on the formatting aspects of the workflow: Latex, FrameMaker and all that. But if you're writing a book for a standard tech publisher, you likely will never even have a direct conversation with whomever does the layout. You turn in structured text and figured to an editor, when then passes it off to layout after editing.

    And if it's any kind of a series, they'll be doing formatting according to a well defined template and style that'll map to the styles in the document you give them.

    So, the actual workflow is that you get a Word template, and write everything in there. The key thing is to follow the Styles religiously - every paragraph should have one as you type it. Think writing in old school HTML, or XML to someone else's Schema.

    Also, try not to even think about formatting; there's no saying what goes on what page based on Page Preview in Word or alternative. If you want a new section, use a section break. This is object-oriented writing, where you're really trying to get the content into the right structure for easy processing later on.

    I recommend working in Outline and Normal/Draft mode only, since that's where you see the structure of what you're doing. Personally, I'm a born again believer in outlining. I outline a chapter, and then jump in and write the part of it I'm thinking about at the moment. With the outline there, it's easy to realize I need to introduce a concept earlier in the chapter and then jump there and do a quick sketch of it, since the earlier section already exists in the structure. The act of writing an outline also helps define all the stuff you didn't know you needed to figure out.

    But don't be a slave to the outline as it exists; structure can need editing as much as prose. Don't be afraid of moving sections and chapters around as helps you communicate better. That's a lot easier to do early in the process.

  • by Garwulf (708651) on Monday December 22, 2008 @02:21AM (#26197481) Homepage

    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...

  • Get to work! (Score:3, Insightful)

    by Fantastic Lad (198284) on Monday December 22, 2008 @05:21AM (#26198173)

    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

  • by Rurik (113882) on Monday December 22, 2008 @07:54AM (#26198755)

    ...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.

This login session: $13.76, but for you $11.88.

Working...