Tools & Surprises For a Tech Book Author? 325
Fubari writes "I have questions for those of you who have written books: what writing tools have you found helpful? I want to start my book off right (so I'm pretty sure I don't want to write it in MS Word). What has and has not worked well for you? So far I have thought of needs like chapter/section management, easy references to figures (charts, diagrams, source code), version control (check in/check out parts like chapters, figures, etc.), and index generation. I would also welcome advice about what I don't know enough to ask about. Did you encounter any surprises that you wish you had known about back when you started out?"
Re:Shouldn't.... (Score:3, Insightful)
Just remember to.. (Score:5, Insightful)
Re:Shouldn't.... (Score:4, Insightful)
Re:Shouldn't.... (Score:2, Insightful)
Being 'tech-savvy' and knowing what is available are two different things. Or are you all knowing and instantly know all the best software out there to use?
If you have a book contract, the publisher has requirements for what they want. If you don't have a contract, you could write it in Notepad or vi for all that it matters....
Re:Shouldn't.... (Score:4, Insightful)
And wise enough to know when to ask for help, something too few tech people know how to do...
Re:LaTeX (Score:3, Insightful)
Re:If you have a publisher, ask them. (Score:5, Insightful)
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.
Been there, used them all (Score:2, Insightful)
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.
Re:My own experiences writing a tech book (Score:4, Insightful)
Right. I used LaTeX because ... well, because I knew it mainly, and because I wanted to get words on paper rather than distract myself with layout early on.
At the end of the process I had to interact with a lot of people and Word would have made the process a hellova lot easier. At 500 odd pages, LaTeX was still taking a while (it builds the PAF by merging all of the DVIs and that takes a while) - I'm not at all convinced Word is any slower. Besides, you're going to write the book on your desktop and you're probably used to using your desktop for all sorts of fancy technical work. The kind of desktops that computer geeks use regularly are more than capable of
Also the spelling and grammar tools for Word are better than comporable tools for LaTeX. And the figure placement in LaTeX - argh! Index management wasn't bad in LaTeX either, but no better than Word. LaTeX might have nice linebreak rules, but it's perfectly happy to do a page break at a stupid place instead of trying harder to squeeze the document - I think LaTeX has stagnated while the GUI world caught up.
PS: My father swears by InDesign for this sort of stuff having migrated to it from Word. Dunno myself and I don't really care, I'm not planning on going through that again.
Re:LaTeX (Score:2, Insightful)
I'll cast my vote as well for LaTeX, perhaps with an extra vote for lyx as well (started with LaTeX, but find lyx speeds things up).
More importantly though, I'm casting a huge vote for BibTeX. Get a frontend to take care of the syntax for you. Once you do that, it's a lifesaver. Pick a reference style once and all you need do is drop a quick ref command with the bibliography entry's name and it build the reference for you, adds the entry into the bibliography (properly formatted and placed), and generally takes care of everything. References are often a chore that distracts from including the content you want; BibTeX makes it simple.
Re:If you have a publisher, ask them. (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.
Get to work! (Score:3, Insightful)
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
Re:Tools Can be a Trap (Score:3, Insightful)
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.