OT?: Writing Style

[Greg Young]

I figured this would be a good place to ask. As many of you know I am
heads down writing now. I had an interesting discussion the other day
with the publisher in terms of writing style. Basically we are trying
to choose between an informal "coach in a book style" or a more formal
style. "Coach in a book" would be where you would often have little
stories, informal writing (eg: often addressing the reader as you, or
using the term "we" as in the author and the reader) and a laid back
overall style. The more formal style would be a similar style to the
way the documents on cqrsinfo.com are written (active voice,
impersonal, rather formal)

What do people here prefer when they read technical books?

Greg

--
Les erreurs de grammaire et de syntaxe ont été incluses pour m'assurer
de votre attention

[Nuno Lopes]

I prefer coaching style.

Nuno

[Peter Ritchie]

Another vote for the coaching style (but, I may be biased ;).

 

cheers -- Peter

--
"Refactoring with Microsoft Visual Studio 2010": http://lynk.at/c13trs
http://PeterRitchie.com/blog/
http://twitter.com/PeterRitchie
http://facebook.com/Peter.Ritchie/
http://www.linkedin.com/in/PeterARitchie
Skype:Peter.a.Ritchie

[sami.d...@gmail.com]

I prefer coaching style as long as it doesn't take twice as much text to describe the same concept.

Sami

On Wed, Apr 27, 2011 at 11:36 AM, Greg Young <gregor...@gmail.com> wrote:

[Jon Gyllensward]

Actually the ideal for me is two books, one reference book and one "applied".

But I guess that we get one and then I prefer coaching :)

[Greg Young]

The general idea is that the coach style does take more text but the
text is simpler (easier to read). When writing formally you often end
up with very dense text (eg: I might spend 3 hours working on one
paragraph to get it just right). Eric's book is definitely written in
the first style (often you have to read, re-read, sentences to get
their meanings. Jimmy's book is far to the other side of the spectrum.

[Marcin Gryszko]

Coaching style for non-English native speakers is much easier to read.

Saludos/Regards

Marcin Gryszko

[Greg Young]

What do you think of haskell for all the examples?

or even better I can use a different language for each example :)

--

[Carl Mäsak]

I agree with Dave Thomas, in that using pronouns and engaging the
reader is preferable to aiming for a formal style filled with passive
voice:

Finding Your Voice
<http://pragdave.pragprog.com/pragdave/2007/03/sywtwab_5_findi.html>

// Carl

[Marcin Gryszko]

Ask yourself the question: why Haskell? Will my audience be able to follow the examples? Or will they have to read first a Haskell book?

(if you are going to write about functional programming, forget my email :))

Saludos/Regards

Marcin Gryszko

[Greg Young]

This is a great example of coaching style. Thanks for the link :)

[Greg Young]

Well many things can fit in one line ... but it was a joke :)

[Jimmy Bogard]

Eh doesn't matter, your editor will muck it all up any way ;)

[AlexY]

I hope it was a joke :)

[Žilvinas Šaltys]

+1 coaching style.

A good example of an easy to read technical book would be:
http://www.amazon.com/Growing-Object-Oriented-Software-Guided-Tests/dp/0321503627

[Richard Dingwall]

Coach style definitely, unless you're writing a formal spec (I guess
the pattern catalog in the blue DDD book is a spec of sorts).

But go easy on the 'we' -- 'you' and 'your' are generally fine
substitutes and they don't make you sound like a patronizing
kindergarten teacher.

--
Richard Dingwall
http://richarddingwall.name

[stacy]

Coaching style for me too. That's how you seem to be anyway (video
courses) so just give us your best YOU.

I would hate to learn/reference Haskel first and then translate back
to c# - real bummer. I think your mainstream audience has been mostly
c# devs on this forum. I would even pre-buy a c# version, but not even
bother with a Haskel version since I don't know Haskel. It's better to
stick with your target audience, IMHO.

Get 'er done!

[Jeremy Lew]

Prefer coaching style, but it's a fine line between "little stories"
and "useless digressions".

[Jason Dentler]

+1000 for Jimmy's "your editor will muck it all up anyway"

Also, a coach style is better when it can be concise. When it can't, the reader will re-read a page 3 and 4 times to get the point, and the book will feel less satisfying. Everything in balance.

Jason

[Angel Java Lopez]

+ coaching style

But to prevent endless discussions (as in Eric Evans DDD book), I would like to read:

- Definitions, with examples, and counterexamples, AND IMPLEMENTATION. That is, if the definition is not clear to someone, example AND counter examples are the way to grasp the new term or concept. As an example: you can write an informal book about group theory (math), but if you add formal spec (what is a group? its axioms), it's a plus to have examples of groups, and counterexamples of what is not a group. And then, a bit of code.

And I would like to read: (after coach style) (after definitions, examples and counter examples) THE FUNDAMENTALS, the "whys" Greg is taking this way???  ;-)

Angel "Java" Lopez
http://www.ajlopez.com
http://twitter.com/ajlopez

[Peter Ritchie]

Hi Jimmy.

I've heard that before about Manning.  What that your experience?

Cheers -- Peter

[Filip Zawada]

+1 for coaching style.
Easier to read and you don't feel like your brain starts to fry when
reading for longer than 30 minutes.

It'd be great if the book contained the "whys", the trade-offs, and
other possible solutions to problems described (e.g.: sync vs async
commands, when to use which and why; how not to over-engineer the system).

Filip Zawada

[Tom Janssens]

I prefer a mix; I read a lot of business books, and in the best books the structure is like this:
(optional) a coaching style intro/anecdote
formal definition
formal explanation & multiple coaching style examples/explanations
formal consequences & coaching style examples/explanations
formal conclusion/recap

Recurse & repeat forever.

My personal top 3 of great business bestsellers all have the mentioned style, and are all bestsellers; they are both accessible and complete
- "Skills for new managers" - McGraw-Hill
- "How to Connect in Business in 90 Seconds or Less" - Nicholas Boothman
- "The Management Myth: Debunking Modern Business Philosophy" - Matthew Stewart
If you have one or can grab one at the library, be sure to do so... IMHO these are great examples of really polished business books...

Examples of not-so-good business bestsellers (style-wise, not content-wise) are "Good to great" (to formal) and "4 hour workweek" (not formal enough).

I hope this answer was helpful, and I wish you the best of luck with your book...

(SPAM: more info about the books at http://www.corebvba.be/blog/post/Continuous-thinking-Essential-business-books-shortlist-3-business-books-everyone-should-have-read.aspx)

[Rob Ashton]

As everybody else has said so far, coaching style is generally more
legible (as long as it isn't flippant and overly familiar, that gets
annoying after a while too).

I'll be more likely to read it if it isn't overly formal

Rob

On Wed, Apr 27, 2011 at 5:36 PM, Greg Young <gregor...@gmail.com> wrote:

[Rafael Peixoto de Azevedo]

Hi, Greg

I don´t mind either coaching or a more formal style,
as long as the stories or the formalisms are synergetic to the learning objectives.
I consider both cited books DDD and GOOS very pleasant and insightful readings.

Fully agree with Angel "Java" Lopez about the importance of
examples, counterexamples, implementation and fundamentals.
They clarify definitions and add exceptional value and consistency to a technical book.

Keep up the excellent work you have been doing!
Cheers,
Rafael

--
Cheers,
Rafael Peixoto de Azevedo
http://www.symprise.net
@RPAzevedo

[João Bragança]

+1 for coaching

[keith Pope]

On 27 April 2011 16:36, Greg Young <gregor...@gmail.com> wrote:
> I figured this would be a good place to ask. As many of you know I am
> heads down writing now. I had an interesting discussion the other day
> with the publisher in terms of writing style. Basically we are trying
> to choose between an informal "coach in a book style" or a more formal
> style. "Coach in a book" would be where you would often have little
> stories, informal writing (eg: often addressing the reader as you, or
> using the term "we" as in the author and the reader) and a laid back
> overall style. The more formal style would be a similar style to the
> way the documents on cqrsinfo.com are written (active voice,
> impersonal, rather formal)
>
> What do people here prefer when they read technical books?

+1 coach

I used this for my book and had great feedback from non-english
speakers. I generally tried to write in a simple inclusive way and
structure things the way I speak.

Good luck I know how much hard work it is!

>
> Greg
>
> --
> Les erreurs de grammaire et de syntaxe ont été incluses pour m'assurer
> de votre attention
>

--
------------
http://www.thepopeisdead.com

[Anton Setiawan]

I vote for coaching style

[Mike Brown]

Greg,
I'm using a coaching style for my book. I've found as a reader that
I'm more engaged with that voice than a more formal academic voice.

On Apr 29, 10:02 am, Rafael Peixoto de Azevedo <RPAzev...@acm.org>
wrote:
> *Hi, Greg*

>
> I don´t mind either coaching or a more formal style,
> as long as the stories or the formalisms are synergetic to the learning
> objectives.
> I consider both cited books DDD and GOOS very pleasant and insightful
> readings.
>
> Fully agree with Angel "Java" Lopez about the importance of
> examples, counterexamples, implementation and fundamentals.
> They clarify definitions and add exceptional value and consistency to a
> technical book.
>

> *Keep up the excellent work you have been doing!
> Cheers,
> Rafael*

>
> On Thu, Apr 28, 2011 at 5:40 AM, Angel Java Lopez <ajlopez2...@gmail.com>wrote:
>
>
>
>
>
> > + coaching style
>
> > But to prevent endless discussions (as in Eric Evans DDD book), I would
> > like to read:
>
> > - Definitions, with examples, and counterexamples, AND IMPLEMENTATION. That
> > is, if the definition is not clear to someone, example AND counter examples
> > are the way to grasp the new term or concept. As an example: you can write
> > an informal book about group theory (math), but if you add formal spec (what
> > is a group? its axioms), it's a plus to have examples of groups, and
> > counterexamples of what is not a group. And then, a bit of code.
>
> > And I would like to read: (after coach style) (after definitions, examples
> > and counter examples) THE FUNDAMENTALS, the "whys" Greg is taking this
> > way???  ;-)
>
> > Angel "Java" Lopez
> >http://www.ajlopez.com
> >http://twitter.com/ajlopez
>

> > On Wed, Apr 27, 2011 at 3:23 PM, Jason Dentler <jasondent...@gmail.com>wrote:
>
> >> +1000 for Jimmy's "your editor will muck it all up anyway"
>
> >> Also, a coach style is better when it can be concise. When it can't, the
> >> reader will re-read a page 3 and 4 times to get the point, and the book will
> >> feel less satisfying. Everything in balance.
>
> >> Jason
>

[GonZa]

I vote for coaching style.