add example

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "[html]": {
+    "editor.formatOnSave": false
+  },
+}

README.md

@@ -1,12 +1,12 @@
 # Even Better Specs
 
-Guidelines for readable and maintainable tests.
+Event Better Specs is an opinionated set of best practices to support the creation of tests that are easy to read and maintain.
 
 ## Guiding principles
 
 Our guidelines are based on two fundamental principles:
 
-- tests must be [self-contained](https://automationpanda.com/2020/07/07/,arrange-act-assert-a-pattern-for-writing-good-tests/), not DRY
+- tests must be [self-contained](https://thoughtbot.com/blog/the-self-contained-test/), not DRY
 - tests should follow the [Arrange-Act-Assert](https://automationpanda.com/2020/07/07/arrange-act-assert-a-pattern-for-writing-good-tests/) pattern
 
 ## Acknowledgment

_config.yml

@@ -5,4 +5,19 @@ theme: just-the-docs
 url: https://evenbetterspecs.github.io
 
 aux_links:
-  Template Repository: https://github.com/just-the-docs/just-the-docs-template
+  GitHub: https://github.com/evenbetterspecs/evenbetterspecs.github.io
+
+# External navigation links
+nav_external_links:
+  # - title: What is it
+  #   url: "#what-is-it"
+  #   hide_icon: true
+  # - title: Guiding principles
+  #   url: "#guiding-principles"
+  #   hide_icon: true
+  - title: Describe what you are testing
+    url: "#describe"
+    hide_icon: true
+  - title: Use context
+    url: "#use-context"
+    hide_icon: true

_sass/custom/custom.scss

@@ -0,0 +1,43 @@
+.bad,
+.good {
+  background: #e8e8e8;
+  padding: 5px 0px 0px 0;
+
+  &::before {
+    padding: 0 10px;
+  }
+
+  .highlight {
+    margin-top: 3px;
+  }
+}
+
+.bad {
+  color: red;
+
+  &::before {
+    content: "BAD";
+  }
+}
+
+.good {
+  color: green;
+
+  &::before {
+    content: "GOOD";
+  }
+}
+
+.main-content {
+  article:not(:last-child) {
+    margin-bottom: 4em;
+  }
+
+  h2 {
+    &:first-child {
+      margin-top: 0;
+    }
+
+    margin-bottom: 0.75em;
+  }
+}

index.html

@@ -0,0 +1,86 @@
+---
+title: Home
+layout: home
+---
+
+<article>
+  <h1>
+      What is it?
+  </h1>
+
+  <p>Event Better Specs is an <i>opinionated</i> set of best practices to support the creation of tests that are easy to read and maintain.</p>
+
+  <h2>
+      Guiding principles
+  </h2>
+
+  <ul>
+    <li>
+      tests must be <a href="https://thoughtbot.com/blog/the-self-contained-test">self-contained</a>, not DRY
+    </li>
+    <li>
+      tests should follow the <a href="https://automationpanda.com/2020/07/07/arrange-act-assert-a-pattern-for-writing-good-tests/">Arrange-Act-Assert</a> pattern
+    </li>
+  </ul>
+</article>
+
+<article>
+  <h2 id="describe">
+    <a href="#describe">
+      Describe what you are testing
+    </a>
+  </h2>
+
+  <p>Be clear about what method you are describing. For instance, use the Ruby documentation convention of <code>.</code> when referring to a class method's name and <code>#</code> when referring to an instance method's name.</p>
+
+  <div class="bad">
+{% highlight ruby %}
+describe 'the authenticate method for User' do
+describe 'if the user is an admin' do
+{% endhighlight %}
+  </div>
+
+  <div class="good">
+{% highlight ruby %}
+describe '.authenticate' do
+describe '#admin?' do
+{% endhighlight %}
+  </div>
+</article>
+
+
+<article>
+  <h2 id="use-context">
+    <a href="#use-context">
+      Use context
+    </a>
+  </h2>
+
+  <p>Contexts are a powerful way to make your tests clear and well organized (they keep tests easy to read). They should start with <code>when</code>.</p>
+
+  <div class="bad">
+{% highlight ruby %}
+it 'has 200 status code if logged in' do
+  expect(response).to respond_with 200
+end
+
+describe 'it returns 401 status code if not logged in' do
+  expect(response).to respond_with 401
+end
+{% endhighlight %}
+  </div>
+
+  <div class="good">
+{% highlight ruby %}
+context 'when logged in' do
+  it { is_expected.to respond_with 200 }
+end
+
+context 'when logged out' do
+  it 'returns 401 status code' do
+    expect(response).to respond_with 401
+  end
+end
+{% endhighlight %}
+  </div>
+</article>