How to cite sources?

[andyw8]

For example:

Use :context instead of the ambiguous :all scope in before/after hooks.

There's a section in Effective Testing With RSpec 3 which provides similar advice:

https://books.google.ca/books?id=8g5QDwAAQBAJ&pg=PT195&lpg=PT195

I think it would be useful to cite this as an 'authoritative' reference (since the book is written by an RSpec maintainer), but I'm not sure what's the most appropriate way. Should it link to Google Books? Or Safari Books Online (which requires paid access)? Or should it just mention the book by its title?

[pirj]

Do you think that adding references to the commit description is sufficient, like e.g. here or here?

Unfortunately, the link to Google Books shows to me:

You have either reached a page that is unavailable for viewing or reached your viewing limit for this book.

However, when sections are being rearranged it's getting harder to get to those references.

Thanks for bringing this up, according to a comment, a number of suggestions in the open issues are influenced by a book you mention and an AmA post on Reddit. It would be nice not to lose track of this.

[andyw8]

I think it's useful to include reference with the commit/PR, but casual readers of the guide probably aren't going to refer back to those. It would be good to provide a way to better understand the reason and context for a particular piece of advice.

Linking to Google Books certainly isn't ideal. Perhaps it should remain neutral and only mention the ISBN, e.g.

Myron Marston, Ian Dees. Effective Testing with RSpec 3. Pragmatic Bookshelf, 2017. ISBN 9781680501988.

[bbatsov]

I agree that this is probably the best approach. Probably the references can just be simple footnotes so they won't distract the reader too much from the content.

[pirj]

This is going to be covered in #98.