No post body was provided.
Things I learned writing my first technical book
11–20 of 34 posts
Re: Things I learned writing my first technical book
#12>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
Re: Things I learned writing my first technical book
#13No post body was provided.
Re: Things I learned writing my first technical book
#14> 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
Re: Things I learned writing my first technical book
#15> 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?
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!
Re: Things I learned writing my first technical book
#16Highly 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: somethin…
If I ever write another "things I learned ..." I would definitely include the three items that you mentioned.
Re: Things I learned writing my first technical book
#17That’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...
Re: Things I learned writing my first technical book
#18That’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 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.
Re: Things I learned writing my first technical book
#19>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
Re: Things I learned writing my first technical book
#20Quoted 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.