Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Things I learned writing my first technical book

blog.klipse.tech

Post reply on HN
Print view View original

21–30 of 34 posts

Re: Things I learned writing my first technical book

#21

Post by raju »

*shameless plug*

> A possible way to make things interesting is to teach the material as a story with fiction characters and a bit of drama.

I am wrapping up the final touches on my latest book, Head First Git[1][2] and I will admit that it wasn't till I was midway through the book when it _really_ dawned on me on how important this is. Some of you might be familiar with the Head First series (if you are not, Head First Design Patterns [3] is a great place to start). It uses a very conversational tone, filled with characters, and lighthearted stories to explain technical issues. Lots of drama, visuals and exercises to help cement ideas.

I took on the project because I feel like I am intimately familiar with Git. Despite that, this book is one of the hardest things I've ever done, mostly because every chapter needs a narrative, with fictional characters, conversations, and problems they are aiming to solve, all while keeping a technical topic in scope.

I know that writing this book has certainly influenced how I might teach or speak on a topic in the future, but the OP is absolutely right—engaging the reader by making the stories about "people" certainly makes the book more interesting and easier to digest.

On the flip-side, it makes the book less _dense_.

[1] https://www.amazon.com/Head-First-Git-Learners-Understanding...

[2] https://learning.oreilly.com/library/view/head-first-git/978...

[3] https://www.amazon.com/Head-First-Design-Patterns-Object-Ori...

(edited for formatting)

Re: Things I learned writing my first technical book

#22

Post by ChrisMarshallNY »

hdjjhhvvhga wrote: post #18
ChrisMarshallNY wrote: post #10

That’s a good list! My fave: > An average writer makes the reader think the author is smart. A good writer makes the reader think the reader is smart. I am quite surprised to see no mention of the importance of an editor. I have to assume that they are no longer as important, these days, as they once were. My mother was a scientific editor, and she was brutal . I once wrote a 400-page book (that was never published).…

I second that. The editor (and translators, if your book is translated later) are the first - and sometimes the only - people who will read your book carefully from the beginning until the end trying to understand each sentence precisely. A reader may be forgiving, thinking that maybe it's their fault they don't understand; the editor will not. I can't imagine publishing a book without an editor - and having it thoro…

The example that I use for the importance of an editor, is Stephen King. He is well-known for disliking editors, and, as his fame grew, he didn't need to use them.

Back in the 1970s ('75 or '76, I believe), a friend told me about this awesome book, called 'Salem's Lot. I got it, and read it. It wasn't too long, and was fine for an addlebrained teenager.

It was the first book that I ever read, that made me look under the bed before I went to sleep. After that, I couldn't get enough of Stephen King.

Nowadays, his books are these monster tomes that make excellent doorstops, but I can't bear to read them, anymore. I think the last book that I read, cover-to-cover, of his, was It. While reading that book, I accidentally put my bookmark in the wrong place, and skipped over 100 pages.

I didn't realize that I had done that, until, near the end, something was referenced from those pages.

It was then, that I decided that maybe I finally had had enough of Stephen King.

Re: Things I learned writing my first technical book

#23

Post by klavik »

tibbar wrote: post #5

> Mind maps are a great visualization tool. Use them smartly I’m curious about this, since my experience with mind maps is that they rapidly grow into giant overly-connected graphs that are very difficult to translate to the sort of linear structure a book or blog post needs. What is OP’s workflow for connecting the two?

Check out OrgPad if you want to see an evolution of mind maps which is actually useful for serious work. For example this single diagram explains why Clojure is great: https://orgpad.com/s/oirCrD.

Re: Things I learned writing my first technical book

#25

Post by viebel »

ziptron wrote: post #24

The articles says: "Writing my first technical book without a publisher would have been a MISSION: IMPOSSIBLE!" But why? Does a publisher provide more than some seed money and motivation? What else am I missing by not using a publisher?

Here are a few things my editor provided me: 1. A process for writing the manuscript 2. Contacting external reviewers 3. Marketing 4. Feedback on a monthly basis

Re: Things I learned writing my first technical book

#26

Post by danbst »

tibbar wrote: post #5

> Mind maps are a great visualization tool. Use them smartly I’m curious about this, since my experience with mind maps is that they rapidly grow into giant overly-connected graphs that are very difficult to translate to the sort of linear structure a book or blog post needs. What is OP’s workflow for connecting the two?

Partly related, the No Bullshit Guide to Linear Algebra has a concept map as a first page, which looks really stunning. Author definitely had spent time mindmapping stuff before writing.

https://minireference.com/miniref/lib/tpl/miniref/dist/image...

Re: Things I learned writing my first technical book

#27

Post by throw349v »

viebel wrote: post #14
tibbar wrote: post #5

> Mind maps are a great visualization tool. Use them smartly I’m curious about this, since my experience with mind maps is that they rapidly grow into giant overly-connected graphs that are very difficult to translate to the sort of linear structure a book or blog post needs. What is OP’s workflow for connecting the two?

Author here: In my book, I used mind maps to let the readers visualize a high level summary of a chapter. Here is an example of such a mind map: https://twitter.com/viebel/status/1469187345580793860

What software did you use to create the mindmap?

Re: Things I learned writing my first technical book

#28

Post by alexott »

viebel wrote: post #17
ChrisMarshallNY wrote: post #10

That’s a good list! My fave: > An average writer makes the reader think the author is smart. A good writer makes the reader think the reader is smart. I am quite surprised to see no mention of the importance of an editor. I have to assume that they are no longer as important, these days, as they once were. My mother was a scientific editor, and she was brutal . I once wrote a 400-page book (that was never published).…

I don't really have a scientific editor at Manning. I have: 1. a TDE (Technical development editor) what behaves more like a project manager and I mentioned them in lesson #47 2. A technical reviewer that makes sure the content is clear for a MQR and I mentioned them in lesson #45 3. A tech proof reader that reviews each and every code snippet when the manuscript is complete A few more...

Manning is very different from other publishers - combination of all these roles allow to produce a high quality content… that’s make it different from other publishers - O’Reilly, APress, etc.

Re: Things I learned writing my first technical book

#29

Post by WalterBright »

ChrisMarshallNY wrote: post #22
hdjjhhvvhga wrote: post #18

Earlier quoted context omitted.

I second that. The editor (and translators, if your book is translated later) are the first - and sometimes the only - people who will read your book carefully from the beginning until the end trying to understand each sentence precisely. A reader may be forgiving, thinking that maybe it's their fault they don't understand; the editor will not. I can't imagine publishing a book without an editor - and having it thoro…

The example that I use for the importance of an editor, is Stephen King. He is well-known for disliking editors, and, as his fame grew, he didn't need to use them. Back in the 1970s ('75 or '76, I believe), a friend told me about this awesome book, called 'Salem's Lot . I got it, and read it. It wasn't too long, and was fine for an addlebrained teenager. It was the first book that I ever read, that made me look under…

King's books started sounding the same to me, so I stopped reading them.

Re: Things I learned writing my first technical book

#30

Post by Ostrogodsky »

ghusbands wrote: post #20
dempedempe wrote: post #13

Quoted post unavailable.

HN guidelines: > Please don't complain about tangential annoyances—things like article or website formats, name collisions, or back-button breakage. They're too common to be interesting.

No post body was provided.
Post reply on HN