1 files changed, 14 insertions, 13 deletions
diff --git a/docs/gmock_for_dummies.md b/docs/gmock_for_dummies.md
index 370f17e1..9f24dcae 100644
--- a/docs/gmock_for_dummies.md
+++ b/docs/gmock_for_dummies.md
@@ -90,14 +90,14 @@ gMock is bundled with googletest.
 ## A Case for Mock Turtles
 
 Let's look at an example. Suppose you are developing a graphics program that
-relies on a [LOGO](http://en.wikipedia.org/wiki/Logo_programming_language)-like
+relies on a [LOGO](https://en.wikipedia.org/wiki/Logo_programming_language)-like
 API for drawing. How would you test that it does the right thing? Well, you can
 run it and compare the screen with a golden screen snapshot, but let's admit it:
 tests like this are expensive to run and fragile (What if you just upgraded to a
 shiny new graphics card that has better anti-aliasing? Suddenly you have to
 update all your golden images.). It would be too painful if all your tests are
 like this. Fortunately, you learned about
-[Dependency Injection](http://en.wikipedia.org/wiki/Dependency_injection) and know the right thing
+[Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) and know the right thing
 to do: instead of having your application talk to the system API directly, wrap
 the API in an interface (say, `Turtle`) and code to that interface:
 
@@ -164,7 +164,7 @@ follow:
 After the process, you should have something like:
 
 ```cpp
-#include "gmock/gmock.h"  // Brings in gMock.
+#include <gmock/gmock.h>  // Brings in gMock.
 
 class MockTurtle : public Turtle {
  public:
@@ -190,10 +190,10 @@ Some people put it in a `_test.cc`. This is fine when the interface being mocked
 `Foo` changes it, your test could break. (You can't really expect `Foo`'s
 maintainer to fix every test that uses `Foo`, can you?)
 
-So, the rule of thumb is: if you need to mock `Foo` and it's owned by others,
-define the mock class in `Foo`'s package (better, in a `testing` sub-package
-such that you can clearly separate production code and testing utilities), put
-it in a `.h` and a `cc_library`. Then everyone can reference them from their
+Generally, you should not mock classes you don't own. If you must mock such a
+class owned by others, define the mock class in `Foo`'s Bazel package (usually
+the same directory or a `testing` sub-directory), and put it in a `.h` and a
+`cc_library` with `testonly=True`. Then everyone can reference them from their
 tests. If `Foo` ever changes, there is only one copy of `MockFoo` to change, and
 only tests that depend on the changed methods need to be fixed.
 
@@ -224,8 +224,8 @@ Here's an example:
 
 ```cpp
 #include "path/to/mock-turtle.h"
-#include "gmock/gmock.h"
-#include "gtest/gtest.h"
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
 
 using ::testing::AtLeast;                         // #1
 
@@ -262,8 +262,9 @@ when you allocate mocks on the heap. You get that automatically if you use the
 `gtest_main` library already.
 
 **Important note:** gMock requires expectations to be set **before** the mock
-functions are called, otherwise the behavior is **undefined**. In particular,
-you mustn't interleave `EXPECT_CALL()s` and calls to the mock functions.
+functions are called, otherwise the behavior is **undefined**. Do not alternate
+between calls to `EXPECT_CALL()` and calls to the mock functions, and do not set
+any expectations on a mock after passing the mock to an API.
 
 This means `EXPECT_CALL()` should be read as expecting that a call will occur
 *in the future*, not that a call has occurred. Why does gMock work like that?
@@ -479,8 +480,8 @@ the *default* action for the function every time (unless, of course, you have a
 `WillRepeatedly()`.).
 
 What can we do inside `WillOnce()` besides `Return()`? You can return a
-reference using `ReturnRef(*variable*)`, or invoke a pre-defined function, among
-[others](gmock_cook_book.md#using-actions).
+reference using `ReturnRef(`*`variable`*`)`, or invoke a pre-defined function,
+among [others](gmock_cook_book.md#using-actions).
 
 **Important note:** The `EXPECT_CALL()` statement evaluates the action clause
 only once, even though the action may be performed many times. Therefore you