gvwilson / 11-techbook Goto Github PK
View Code? Open in Web Editor NEWEleven Quick Tips on Writing a Technical Book
License: Other
Eleven Quick Tips on Writing a Technical Book
License: Other
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.
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
Maybe add also about how to make your book available?
Something about Open access licenses? Contributions?
Other reasons to write blog post:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.