Things I learned writing my first technical book | Hacker News Reader

Things I learned writing my first technical book

blog.klipse.tech

142 pointseigenhombre28 comments

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). She edited it for me, and it may be the most perfect prose I’ve ever produced (but it was out of date and technically irrelevant, by the time it was ready).

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.

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 thoroughly reviewed by at least two specialist in the field, even if you self-publish. But since it's expensive, I believe many people dispense with that.

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.

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

> I have to assume that they are no longer as important, these days, as they once were.

They are, but just that folks (in tech?) are losing sight of what good editors would bring to the table: https://apenwarr.ca/log/20060721 (grand old unified relational documentation) | https://apenwarr.ca/log/20090506 (the value of professional copy-editing)

>The “why” is more important than the “what”.

>The “what” is more important than the “how”.

This also feels very applicable to comments in source code, or internal documentation in general

Totally agree. Especially in READMEs

> 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?

I ran in the same issue. And I've created Coco - a Content-as-Code framework to split large graphs / mind maps into small, understandable chunks.

You can take a look at how Coco works here: http://metamn.io/react/on-design-systems-3/ (All figures except the first were made with Coco)

Yep. Half the fun/challenge of writing a book (I’m on my fourth) is finding the right linear sequence.

Author here: More challenge than fun!

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?

Lucidchart

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.

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...

*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)

This is probably a good list. Some points I don't agree with, but, as a person who kind of invested in the book by buying it while it was in MEAP at Manning, having high expectations for it, I can say I was extremely disappointed with the content. I found some passages unclear at times and the whole idea of mapping the data oriented programming approach taken from functional programming to a general purpose way of designing programs and using JS to convey the message, somehow didn't make it click for me.

It's a good list of tips and I hope the book was successful and helped people!

Highly valuable tips & tricks, all of them encouraging, which is rare. Usually authors start with 'Don't write a book' or 'Think twice before start writing a book'.

I've also started writing a technical book and I find it challenging in the same pleasant way.

Writing is much much harder than programming because you can't test prose and you don't have a programming language. But the deliverables are the same: something which runs flawlessly on a processor.

Writing a book is much harder than writing articles because a book has to stay interesting for hours, while an article for just a couple of minutes.

Getting a writing mindset is far harder than getting a programming mindset: I can write code any day, any time but sometimes I can't write a paragraph a day.

If I ever write another "things I learned ..." I would definitely include the three items that you mentioned.

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

I don't think it's mission:impossible for some people...but for people such as myself, my editor really gave a sense of external accountability + pressure to finish. If I didn't have an editor, I'm 90% sure I would have stopped around 2 chapters in and tabled it for some other time (read as: never touched it again). Also, there are perks to having a formal publisher: you have reviewers, copy editors, and formatters who really make sure that things are really standardized. That really allowed me to focus on writing.

Most of it could be said about any UX in general

Or about making a product

Reply on news.ycombinator.com