gvwilson / 11-techbook

Eleven Quick Tips on Writing a Technical Book

Dr. Greg Wilson is a programmer, author, and educator based in Toronto. He co-founded Software Carpentry, The Architecture of Open Source Applications, and It Will Never Work in Theory, and has written, co-written, and edited fourteen technical books and two for children. Greg is a member of the Python Software Foundation and a recipient of ACM SIGSOFT's Influential Educator of the Year award; he currently works for Plotly as a software engineering manager.

• Personal site
• Software Design by Example in Python
• Software Design by Example in JavaScript
• Research Software Engineering with Python
• JavaScript for Data Science
• Teaching Tech Together
• It Will Never Work in Theory
• The Architecture of Open Source Applications
• Beautiful Code
• Ten simple rules for writing a technical book
• Twelve quick tips for software design
• Ten quick tips for staying safe online
• Ten quick tips for making things findable
• Ten simple rules for helping newcomers become contributors to open projects
• Ten quick tips for creating an effective lesson
• Ten quick tips for teaching programming

11-techbook's Issues

Blogs to books

Hey Greg

I think most of this is great advice. But I don't think #2 is: or at least, not starting with a book might be, but I don't think starting with blog posts is. Have you ever written (or tried to write) a book that way? I have, several times, and it's always been a disaster. Whereas I've co-written a couple of books, and am half-way through another, linearly, forwards, and that's worked much better.

I think the trouble with writing a bunch of blog posts is that they will almost always be stand-alone things but the temptation will be to glue them together, somehow, with some editing, to make the book. And I think that almost never works. Sure, if you regard the blog posts as exercises, and and a way of forming ideas, and possibly examples, that's fine. But when you come to write the book, I think it will almost always need a complete, essentially from-scratch rewrite in order to have any kind of flow or coherence; and I think the existence of all that text in the posts tends to make people shy away from that.

The only time I can see this not being the case is if the book is really a collection of independent or very loosely connected chapters. I know you've edited a lot of books like that, and that's obviously fine; but I struggle to believe any of the good technical books I've read started (or could really have started) as a sequence of blog posts or similar.

I'm slightly unsure about the bit about audience too; but I'll raise a separate issue for that.

Hope this is useful.

Nick

To add to blog post

Other reasons to write blog post:

• to receive feedback on that particular section.
• summarize bibliography: it is a very good way to explain (and see how much you understood) one or several related papers. Presenting them in a blog post (or series of blog posts) helps you summarize, and if you get feedback it can help you find missing or newer bibliography.
• Blog posts definitely help to refine ideas.

Leaner Personas

I think you'll almost certainly disagree with this, but I'll say it anyway.

A lot of people advocate, as you do, writing for a very well-defined group of readers. And it seems like common sense. But I don't really agree with it. I agree that if you write something that assumes some particular knowledge, it's good to state and know that; but beyond that, I think it can do as much harm as good. People are complex and have weird mixes of experiences and aptitudes and interests, and I think the job of a writier is to lay out the information in as clear and accessible a way as possible, without making too many assumptions about the reader. Even if the reader does fit the writer's experiences or broad assumptions, it doesn't mean they'll necessarily us the same language, or think about things the same way, so some of the benefit of introductory material in an advanced books isn't so much to allow novices to learn at breakneck speed as to allow the writer to explain how (s)he works and thinks about things; and that can be extremely useful.

Anyway, as I say, you won't agree with this, and my opinion is definitely a minority one; but I think assuming a particular reader can be arrogant and destructive.

Add a point for writing together?

Ship

Maybe add also about how to make your book available?
Something about Open access licenses? Contributions?