Writing a book

[onion2k]

I know several of the folks here contributed to a PHP book fairly recently.. any tips on writing tech stuff? Did you write the code examples and then explain what you did? Or write the text and then write the code to go with it?

[BuzzLY]

Are you looking to write an article, or a book? The techniques are a little different. For example, with a book, you really need to plan it all out with an outline before you get into writing anything.

We created a detailed outline of what our chapters would contain, including the code. Once the outline was complete and approved, I planned out what the application was supposed to do (much like you do for any coding project), what concepts I wanted to convey, then wrote the application. I then wrote out the How It Works section explaining the code, which usually prompted me to go back and make changes to the code. I'd go back and forth like this until the code and How It Works was done.

Then, I'd write the introductions to the chapter, run the code and take the appropriate screenshots, and my first draft would be complete. Then Jason yells at me for not following standards, and I have to redo all my code again 😃

[Weedpacket]

Meanwhile, everyone else was out in the kitchen, discussing the relative merits of low-cholesterol salad dressings.... 🙂

[drawmack]

You know somethings have no point, like low cholesterol salad dressing. I mean what's the point of eating all those flavorless veggies if you can't dump something unhealthy on top 😃

[Tekime]

I certainly haven't written any books, but I've written a lot hardware reviews, some software/programming articles, technical documentation, and I'm doing my second public PHP presentation this month.

When I'm doing reviews, I always start with an overview of what I'll be writing about: I cover the scope and purpose of the document, and what I hope to accomplish before it's done. Then the reader can bug out if it isn't in their interest, instead of realizing four pages deep that they don't care what I'm talking about.

Planning is key, always create a rough outline of what you are covering before the document gets wildly out of scope.

Always back up an argument with sound factual data and sources. An opinion isn't much good if there is no reasoning behind it.

If you're listing code, make it clear what versions and platform you are using.

Don't be overly talkative, but have some personality. Half the tech books I pick up end up back on the bookshelf because they either:

a) Have no real content and lots of fluffy chatter.
or
b) Have lots of content, but are so cryptic and/or boring it makes your head spin.

Obviously, use proper grammar and spelling whenever possible. Your editor will love you, and you'll spend less time dealing with revisions.

Strunk and White's The Elements of Style is a classic reference for proper usage and common mistakes in the English language.

Most of this is probably obvious to you anyway, but hopefully there is something here that can be of use to you.