What advice would you give to authors of programming books, blogs, web casts etc?

Question

This post was inspired partly by two programming books I read recently and partly by Jon Skeet's advice on answering technical questions helpfully.

Most of the stackoverflow questions on learning resources (books, blogs etc.) are along the lines of "Where can I find a [resource x] on [subject y]?"

I'd like to turn this around and ask, based on your experience, what advice you'd give an author. I'm not an author but maybe feedback to this question would be of interest, not just to consumers, but to the many authors and publishers out there.

Please limit your responses to content issues rather than stylistic ones.

Here are a few examples based on books I read recently:

1. It's okay to introduce concepts that are covered in more detail later but don't get into a detailed discussion before you've actually explained what's going on.
2. Keep all code examples as simple and to the point as possible i.e. don't introduce tangential concepts/syntax that are not essential to conveying the point of the example.
3. For books, provide a decent index that is designed by an information architect not a computer.

Answer 1

Certainly for blogs - try and keep it short and to the point.

I can relate to that as a very amateur blog author - I've had the best feedback on my blog from a 20-line post, the ones that are my attempt at in-depth coverage... nothing!

As a blog reader - I usually find a blog whilst searching for the answer to a particular question - if I haven't found what I need in the first few seconds, I'm outta there!

Answer 2

Keep it simple, dont try to explain things in a fancy manner, usually i tend to grasp better when the lecture or code is explained in a simple way

Answer 3

KISS.

Lots of worked examples and diagrams - a picture is worth 1000 words.

Answer 4

Read between the lines of the question - what is asked is often based on incomplete understanding of the problem, and as the provider of a solution, you need to go the extra mile to give the complete useful explanation of the problem.

Do address the question as succinctly as possible as early as possible in the writing. If you need to expand or expound, put it after the quick and easy explanation.

Answer 5

Another piece of advice for a blog would be to build an identity and have a core set of ideals/values that persist through all of your writings (eg: Joel's views on treating programmers well, making simple and metaphorical UIs, etc). Also try to have a uniform style so that people will instinctively know they're reading something written by you. In this manner you can "brand" yourself and be distinctive.

Remember, anything you can do to be remarkable will set you apart from everyone else and instantly increase the perceived quality of your work. Note that "remarkable" doesn't have to mean "greater than everyone else" or "superior." It just means "worth making a remark about." See Seth Godin's writings for more thoughts on "remarkableness" and branding yourself. It's worth taking a look at for any blogger or writer.

A good example of this principle in the programming books world is the "Head First" series. Sure, not everyone likes their method, but they've been very successful and their readers tend to sing praises for the books and how interesting they are.

Answer 6

Lots and lots of usable code. If you can't take the code and use it with a little modification. It's not worth having.

Answer 7

Don't go and just write your book like 'that other author'. I hate having&reading books that are just like 'those other books'. Use your own approach, you're bound to have at least one new idea worth reading.