Test-Driven Writing

# Test-Driven Writing

<div>
  <small>Presented By<br><a href="https://mherman.org">Michael Herman</a><br><a href="https://twitter.com/mikeherman">@mikeherman</a> </span>
</div>

---

### Agenda

##### (1) Intro (~ 10 minutes)

1. About Me
1. Objectives

##### (2) Theory (~ 40 minutes)

1. Test-Driven Development
1. Test-Driven Writing
1. Learning to Learn

##### (3) Break (~ 10 minutes)

##### (4) Practice (~ 2 hours)

1. Red
1. Green
1. Refactor

##### (5) Next Steps (~ 5 minutes)

---

## Intro

---

### About Michael

```
$ whoami
michael.herman
```

#### Senior Software Engineer from Denver, CO

1. Python and JavaScript Contractor
1. [TestDriven.io](https://testdriven.io)

#### Also

1. Founder and Organizer of [Denver Node.js Meetup Group](https://www.meetup.com/Node-js-Denver-Boulder/)
1. Former Lead Instructor at [Galvanize](https://www.galvanize.com/)
1. Co-founder/author of [Real Python](https://realpython.com)
1. 😍 - [tech writing/education](http://mherman.org), [open source](http://github.com/mjhea0), [financial models](http://www.starterfinancialmodel.com/), [radiohead](http://radiohead.com/)

---

### Objectives

By the end of this training, you should be able to...

1. Explain what AWS EC2 and ECS are and why you may need to use each of them

1. Develop a technical blog post using the Red-Green-Refactor process

1. Describe the difference between a step-by-step tutorial, a high-level overview, a low-level reference piece, and a list post

1. Explain what narrative is and why it's important

1. Engage in reverse-planning by writing objectives first

1. Describe the learning to learn process

---

## Theory

---

### What is Test-Driven Development?

[Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development) (TDD) is a methodology in software development that focuses on an iterative development cycle where the emphasis is placed on writing test cases before the actual feature or function is written.

- verify, code, verify, repeat
- validate, design, validate, repeat

#### TDD

1. Utilizes repetition of a short development cycle
1. Combines building and testing
1. Helps ensure correctness of code—but also helps to indirectly evolve the design and architecture of the project at hand.

<div style="text-align:center;">
  "Code without tests is broken by design."<br>- Jacob Kaplan-Moss<br>(co-creator of <a href="https://www.djangoproject.com/">Django</a>)
</div>

---

### Red-Green-Refactor

TDD usually follows the "Red-Green-Refactor" cycle:

![tdd](images/tdd.png)

1. It can be slower in the short-term, but it generally improves the quality of the software project in the long run.

1. Having adequate test coverage acts as a safeguard so you don't accidentally change the functionality.

1. Finally, test suites can encapsulate the expectations of your software project so that your project's stakeholders (current self, future self, everyone else) can better understand the project.

---

### Check for Understanding

#### (1) What is Test-Driven Development?

#### (2) Can the Test-Driven model be applied to writing?

- Is there a way that you can write "tests" beforehand that tell you what to write and what not to write?
- Can you "encapsulate" the expectations of your tutorial so that your readers can better understand it?
- Will tests help to strengthen your thesis?
- Can you make a strong, upfront case that your readers can easily assert against?

🤔

---

### Test-Driven Writing

![tdd](images/test-driven-writing.png)

The goals are different:

1. You SHOULD NOT always adhere to the Test-Driven process! The Test-Driven model can constrain the artistic side when practiced rigidly. Constrains can be good at times, though. They can help you stay focused and keep you within scope.
1. You CANNOT fully test out your writing. ([Watson API](https://www.ibm.com/watson/services/natural-language-understanding/)?)

---

### Test-Driven Writing Process

- Start with the **audience**, **article type**, **narrative** (e.g.,the common thread) and **objectives**.

- Then, write out an **outline** and possibly the **conclusion**.

- As you write out each section from the outline, look back to the **audience**, **narrative**, and **objectives** to ensure that you are staying on track.

---

### Learning to Learn

Developers must be lifelong learners!

##### Learning to learn process:

1. Set the state
1. Play
1. Reflect

<br>

<small>

Sources:

1. http://slides.com/evanmoore/learning-to-learn
1. https://github.com/realpython/learning
1. https://css-tricks.com/learning-to-learn/

</small>

---

### Learning to Learn (continued...)

#### (1) Set the Stage

- Slow down, get your mind right

- Eliminate distractions—close browser tabs, silence your phone, use the Pomodoro method

- Clarify the _what_ and _why_: What is it that you're trying to achieve? Why is that important?

- Focus on the process—The process is much more important than the end product:
    - How do you approach a problem?
    - What do you do when you get stuck?
    - Can you brute force your way through?

---

### Learning to Learn (continued...)

#### (2) Play

- Wrestle with it. Take risks and experiment. The most fruitful place to be is at the edge of your ability.

- Be [vulnerable](https://www.ted.com/talks/brene_brown_on_vulnerability?language=en).

- Have fun! Recognize if you're in 'fight or flight' mode, and take steps to get yourself back in a positive state of mind.

#### (3) Reflect

- Self assess

- Ask new questions and discover new things

- Provide continuous feedback

- Ask the following questions at the end of each writing session:
    - What were my objectives?
    - How far did I get? How much is left?
    - How was the process? Am I on the right track?

---

## Practice

---

### Red

*Scenario: Your boss wants you to write an article on "Understanding OAuth 2.0 and OpenID Connect".*

Where do you start?

| Component    | Description                                                                                |
|--------------|--------------------------------------------------------------------------------------------|
| Audience     | Your readers (e.g., current self, future self, and outside readers)                        |
| Article Type | Step-by-step tutorial, a high-level overview, a low-level reference piece, and a list post |
| Narrative    | What's the common thread taking the reader from the top of the article to the bottom?      |
| Objectives   | What should your readers take away from your article?                                      |

<br>

Your turn! Open up your favorite markdown editor...

---

### Red (continued...)

#### Who is your audience?

Put yourself in their shoes:

1. What do they know?
1. What do they need to know?

<br>

#### What kind of article do you want to write?

1. Step-by-step tutorial (short code snippets, practical examples)
1. High-level overview (comparison posts, starting with a question, taking someone on a journey)
1. Low-level reference piece (i.e., API docs)
1. List post (i.e., 5 ways you can do something better, etc.)

---

### Red (continued...)

#### How does the article type affect the narrative?

Narrative examples:

1. Building on a project
1. Real-world analogy or theme
1. Working toward a common goal, like contributing to an open source project
1. Answering a question

<br>

#### What makes for a good objective?

1. Objectives should be specific, measurable, achievable.
1. They generally start with action verbs
    - GOOD: explain, assess, analyze, describe, identify, evaluate
    - BAD: understand, gain

---

### Green/Refactor

**What's next?**

- Create a basic outline

- As you write out each section from the outline, look back to the **audience**, **narrative**, and **objectives** to ensure that you are staying on track.

**Recommendations**

<div class="grid">
  <div style="float: left; width: 50%;">
    <ul>
      <li>Eliminate distractions</li>
      <li>Time-box yourself</li>
      <li>Try not to revise as you write (inspiration is fleeting!)</li>
      <li>Force yourself to step away</li>
      <li>Think about the length (shorter posts generally receive more comments, longer posts get more SEO love)</li>
    </ul>
  </div>
  <div style="float: left; width: 50%;">
    <div text-align="center">
        <img src="images/tweet2.png" style="max-width: 90%;" alt="tweet"
    </div>
  </div>
</div>

---

### That's it!

##### Additional Resources

1. [Best Practices for Documenting Technical Procedures](https://www.slideshare.net/MelanieSeibert/best-practices-for-documenting-technical-procedures)
1. [What to Write](https://jacobian.org/2009/nov/10/what-to-write/)
1. [Write the Docs - Documentation Guide](http://www.writethedocs.org/guide/)
1. [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/)
1. [Google Developer Documentation Style Guide](https://developers.google.com/style/)

##### Contact Info

1. [michael@mherman.org](mailto:michael@mherman.org)
1. [mherman.org](https://mherman.org)
1. [@mikeherman](https://twitter.com/mikeherman)

##### Questions?

✌️