diff --git a/doc/markdown/assertions.md b/doc/markdown/assertions.md
index 7888581..5d8b233 100644
--- a/doc/markdown/assertions.md
+++ b/doc/markdown/assertions.md
@@ -81,7 +81,7 @@
 
 --------
 
-- 
+- Check out the [**example**](../../examples/assertion_macros/main.cpp) which shows many of these macros
 - Do not wrap assertion macros in ```try```/```catch``` - the REQUIRE macros throw exceptions to end the test case execution!
 
 ---------------
diff --git a/doc/markdown/faq.md b/doc/markdown/faq.md
index 99e6205..c0a743c 100644
--- a/doc/markdown/faq.md
+++ b/doc/markdown/faq.md
@@ -1,6 +1,8 @@
 ## FAQ
 
-- linker issues (_IMPLEMENT, etc)...
+#TODO...
+
+- linker issues? Make sure you have instantiated the test runner in only one source file.
 
 - stringification issues - if operator<<(ostream for a type is visible only in one source file...
 
@@ -20,7 +22,7 @@
 
 - how subcases work - http://pastebin.com/rwghFzK4 - or look in the repo
 
-- why c++98?
+- why c++98? because.
 
 - will the library support checking for memory leaks? no. use tools like valgrind or the sanitizers.
 
diff --git a/doc/markdown/features.md b/doc/markdown/features.md
index 7bdb798..9d64c17 100644
--- a/doc/markdown/features.md
+++ b/doc/markdown/features.md
@@ -39,6 +39,7 @@
 - offers a way to remove **everything** testing-related from the binary with the [**```DOCTEST_CONFIG_DISABLE```**](configuration.md) macro
 - tests are registered automatically - no need to add them to a collection manually
 - supports [**subcases**](testcases.md#subcases) for easy setup/teardown of tests (also supports the retro [**test fixtures**](testcases.md#test-fixtures) with classes)
+- output from all compilers on all platforms is the same - byte by byte
 - supports [**BDD style**](testcases.md#bdd-style) tests
 - only one core [**assertion macro**](assertions.md) for comparisons - standard C++ operators are used for the comparison (less than, equal, greater than...) - yet the full expression is decomposed and left and right values of the expression are logged
 - assertion macros for [**exceptions**](assertions.md) - if something should or shouldn't throw
diff --git a/doc/markdown/testcases.md b/doc/markdown/testcases.md
index 2fe8793..e556ea8 100644
--- a/doc/markdown/testcases.md
+++ b/doc/markdown/testcases.md
@@ -1,10 +1,98 @@
 ## Test cases
 
+While **doctest** fully supports the traditional, xUnit, style of class-based fixtures containing test case methods this is not the preferred style.
+
+Instead **doctest** provides a powerful mechanism for nesting subcases within a test case. For a more detailed discussion see the [**tutorial**](tutorial.md#test-cases-and-subcases).
+
+Test cases and subcases are very easy to use in practice:
+
+* **TEST_CASE(** _test name_ **)**
+* **SUBCASE(** _subcase name_ **)**
+
+_test name_ and _subcase name_ are free form, quoted, strings. Test names must be unique within the Catch executable.
+
+For examples see the [Tutorial](tutorial.md)
+
+## BDD-style test cases
+
+In addition to **doctest**'s take on the classic style of test cases, **doctest** supports an alternative syntax that allow tests to be written as "executable specifications" (one of the early goals of [Behaviour Driven Development](http://dannorth.net/introducing-bdd/)). This set of macros map on to ```TEST_CASE```s and ```SUBCASE```s, with a little internal support to make them smoother to work with.
+
+* **SCENARIO(** _scenario name_ **)**
+
+This macro maps onto ```TEST_CASE``` and works in the same way, except that the test case name will be prefixed by "Scenario: "
+
+* **GIVEN(** _something_ **)**
+* **WHEN(** _something_ **)**
+* **THEN(** _something_ **)**
+
+These macros map onto ```SUBCASE```s except that the subcase names are the _something_s prefixed by "given: ", "when: " or "then: " respectively.
+
+* **AND_WHEN(** _something_ **)**
+* **AND_THEN(** _something_ **)**
+
+Similar to ```WHEN``` and ```THEN``` except that the prefixes start with "and ". These are used to chain ```WHEN```s and ```THEN```s together.
+
+When any of these macros are used the console reporter recognises them and formats the test case header such that the Givens, Whens and Thens are aligned to aid readability.
+
+Other than the additional prefixes and the formatting in the console reporter these macros behave exactly as ```TEST_CASE```s and ```SUBCASE```s. As such there is nothing enforcing the correct sequencing of these macros - that's up to the programmer!
+
+## Test fixtures
+
+Although **doctest** allows you to group tests together as subcases within a test case, it can still be convenient, sometimes, to group them using a more traditional test fixture. **doctest** fully supports this too. You define the test fixture as a simple structure:
+
+```c++
+class UniqueTestsFixture {
+  private:
+   static int uniqueID;
+  protected:
+   DBConnection conn;
+  public:
+   UniqueTestsFixture() : conn(DBConnection::createConnection("myDB")) {
+   }
+  protected:
+   int getID() {
+     return ++uniqueID;
+   }
+ };
+
+ int UniqueTestsFixture::uniqueID = 0;
+
+ TEST_CASE_FIXTURE(UniqueTestsFixture, "Create Employee/No Name") {
+   REQUIRE_THROWS(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), ""));
+ }
+ TEST_CASE_METHOD(UniqueTestsFixture, "Create Employee/Normal") {
+   REQUIRE(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), "Joe Bloggs"));
+ }
+```
+
+The two test cases here will create uniquely-named derived classes of UniqueTestsFixture and thus can access the `getID()` protected method and `conn` member variables. This ensures that both the test cases are able to create a DBConnection using the same method (DRY principle) and that any ID's created are unique such that the order that tests are executed does not matter.
+
+## Test suites
+
+Test cases can be grouped into test suites. This is done with the ```TEST_SUITE()``` and ```TEST_SUITE_END()``` macros.
+
+For example:
+
+```c++
+TEST_CASE("") {} // not part of any test suite
+
+TEST_SUITE("math");
+
+TEST_CASE("") {} // part of the math test suite
+TEST_CASE("") {} // part of the math test suite
+
+TEST_SUITE_END();
+
+TEST_CASE("") {} // not part of any test suite
+```
+
+Then test cases from specific test suites can be executed with the help of filters - check out the [**command line**](commandline.md)
+
+------
+
+- Check out the [**example**](../../examples/subcases_and_bdd/main.cpp)
 - Tests are registered from top to bottom of each processed cpp after the headers have been preprocessed and included but there is no ordering between cpp files.
-
-- Tests are registered globally within each shared object/executable. If a test is defined in a header and that header is used in an executable and in a shared object, then the test is registered in both places. To see how to invoke tests from a shared object check out **multi_dll** from the examples folder.
-
-test case and subcase names must be string literals
+- Test case and subcase names must be string literals
 
 ---------------