How do you write a technical book?

Question

I want to write a technical book. What is a good way/software to write it?

What is important to me,

1. I want to be editing text, not fighting formating. So no word like systems.
2. Automatic syntax highlighting.
3. Templatable.
4. A way for users to leave feedback on specific parts of the book. Like Djangobook
5. Not a wiki. (I don't think a wiki is a correct medium to write a book)

I use sphinx, sphinx.pocoo.org/intro.html, which is mostly there(everything except 4), but I want to know what other options I have, and what can get me 4.

Answer 1

The answer from the year 1992 is LaTeX ;)

Answer 2

Are you intending to get this book published professionally? If so, find a publisher who's interested first, and find out what they want you to write in. Being able to work closely with editors, proof readers, the production department etc is vital.

For what it's worth, I wrote the first edition of C# in Depth in Word, and the second edition is being written in a subset of the DocBook format, using XMLmind XML editor. I didn't find myself fighting Word too much in the first edition, and the second edition has taken a bit longer to get started with but is now coming on without much impedance from the format.

No syntax highlighting, mind you...

Answer 3

I just completed writing my first book - ASP.NET 3.5 Social Networking - under Packt Publishing. I agree with Jon Skeet in that you should pitch your idea to a publisher and get that lined up prior to investing too much thought in your book idea. While you can certainly self publish with companies such as Amazon and MANY MANY more...the marketing side of getting your book into Barnes and Noble, Borders, etc. is not something you can do on your own. Heck...you can get my book from Target or WalMart if you wanted too.

If your question is deeper than this and you want to know where to go to get started I will explain what I did (and I am a no-body unlike Mr. Skeet! ...which may be a more relevant perspective!). I of course started up a blog and published more than a standard couple of paragraphs. I did this prior to wanting to write a book. This gives you something to point to when someone wants to see your writing style and capabilities. Next (thanks to Brian Loesgen of Microsoft) I submitted myself to various publishing companies to start doing technical reviews of the latest books coming out. I have mentioned the benefits to doing this many times before - even if you have no interest in writing books. By doing a technical review you get super early access to new content a year before anyone else. You usually get to see many different styles of writing. You get your name in the book as part of the technical reviewing/editing team. You usually get a copy of the book once it is published for free. Depending on the company you may also get some cash for the gig (O'Reilly). I have done this sort of work for Manning and O'Reilly.

The biggest thing to take away from doing technical reviews is that now someone at these publishing companies knows you. At the bottom of every review I have done is the question "Do you know someone that we should know of to author a book for us?" or "Do you have any suggestions for a new book idea?" etc. This is your chance to get your name and ideas in there.

All of the publishing companies (at least for technical books) are way open to new authors and new ideas. They have acquisition editors who's full time job is to come up with new ideas and new authors. They will help you with every step of the way from building up your idea into a good topic for a book all the way through the editing process.

One statement that I was told frequently before I started writing and after - don't plan to get rich off of writing a book! You will actually make more money writing articles for ezines and magazines. Write the book for yourself. Write the book for your resume. Write the book for a sense of accomplishment!

1. I want to be editing text, not fighting formatting. So no word like systems. Frequently the publisher will specify the tool that is to be used (if you go with a big publisher). All of the books that I have reviewed to include the one that I wrote were managed in Word. This is rarely your choice.
2. Automatic syntax highlighting. When I copy paste from Visual Studio into Word all of the syntax highlighting follows along with it. The publisher wants me to then make it the "code" style (which effectively removes this coloring) so that it can be managed by way of a style down the road before going to the printer.
3. Templatable Word is very templateable - why fight it? :P
4. A way for users to leave feedback on specific parts of the book. Like Djangobook I set up a web site for my book. There I have a blog and a forum. I post updates to both places and help the users with various issues through the forum. This has been well received. I have also set up a codeplex project for the books code so that the people that invested in the book can grow the code base together if they so chose.
5. Not a wiki. (I don't think a wiki is a correct medium to write a book) I agree. The biggest issue is always going to be how you plan to publish your book. Even if you plan to self publish the manuscript will have to conform to the publishing tools you have in hand. Get these topics worked out first (who is publishing and how) and then decide on what tools you can use.