Add reference to Effective Testing with RSpec 3

[andyw8]

As discussed in #87.

I've gone for a style based on Martin Fowler's books – using an abbreviated name in the main body of the text.

From the book:

RSpec 3 fixed the confusing wording by renaming :each to :example and :all to :context. The old names :each and :all are still there for backward compatibility with existing specs, but we recommend using only the newer terms.

[pirj]

Loving it 👍

[pirj]

How do you feel about using the same style as link below? E.g.:

<sup>[[etwr3, Chapter 7](#etwr3)]</sup>

[andyw8]

Yes, I considered that, but since they serve quite distinct purpose, I think it would be good to differentiate them:

• The [link] links are 'utilitarian' – they provide a way to direct people to particular sections of the document, so can be less prominent.
• The reference links are part of the narrative – they credit the origin of the guidelines, so should be more prominent.

What do you think?

[bbatsov]

I concur.

[pirj]

My concern is that it doesn't look too attractive

How do you feel about using a blockquote instead?

[andyw8]

Hmm, that seems semantically wrong, since it's not actually a quote.

Perhaps we can revisit this after #95?

[pirj]

WDYT of keeping this open to remind us to add proper references, and meanwhile play with AsciiDoc?

[andyw8]

Sure, it's not urgent.

[pirj]

Let's figure out some generic solution to this since context for all the recommendations has been recently made untrackable (see #98).