Agenda

Agenda

(1) Intro (~ 10 minutes)

1. About Me
2. Objectives

Agenda

(1) Intro (~ 10 minutes)

1. About Me
2. Objectives

(2) Theory (~ 40 minutes)

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

Agenda

(1) Intro (~ 10 minutes)

1. About Me
2. Objectives

(2) Theory (~ 40 minutes)

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

(3) Break (~ 10 minutes)

Agenda

(1) Intro (~ 10 minutes)

1. About Me
2. Objectives

(2) Theory (~ 40 minutes)

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

(3) Break (~ 10 minutes)

(4) Practice (~ 2 hours)

1. Red
2. Green
3. Refactor

Agenda

(1) Intro (~ 10 minutes)

1. About Me
2. Objectives

(2) Theory (~ 40 minutes)

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

(3) Break (~ 10 minutes)

(4) Practice (~ 2 hours)

1. Red
2. Green
3. Refactor

(5) Next Steps (~ 5 minutes)

About Michael

$ whoami
michael.herman

About Michael

$ whoami
michael.herman

Senior Software Engineer from Denver, CO

1. Python and JavaScript Contractor
2. TestDriven.io

About Michael

$ whoami
michael.herman

Senior Software Engineer from Denver, CO

1. Python and JavaScript Contractor
2. TestDriven.io

Also

1. Founder and Organizer of Denver Node.js Meetup Group
2. Former Lead Instructor at Galvanize
3. Co-founder/author of Real Python
4. 😍 - tech writing/education, open source, financial models, radiohead

Objectives

Objectives

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5. Engage in reverse-planning by writing objectives first

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

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

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

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

5. Engage in reverse-planning by writing objectives first

6. Describe the learning to learn process

What is Test-Driven Development?

What is Test-Driven Development?

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

What is Test-Driven Development?

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
2. Combines building and testing
3. Helps ensure correctness of code—but also helps to indirectly evolve the design and architecture of the project at hand.

What is Test-Driven Development?

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
2. Combines building and testing
3. Helps ensure correctness of code—but also helps to indirectly evolve the design and architecture of the project at hand.

Red-Green-Refactor

Red-Green-Refactor

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

Red-Green-Refactor

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

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

Red-Green-Refactor

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

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

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

Red-Green-Refactor

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

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

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

3. 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

Check for Understanding

(1) What is Test-Driven Development?

Check for Understanding

(1) What is Test-Driven Development?

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

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

Test-Driven Writing

Test-Driven Writing

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.
2. You CANNOT fully test out your writing. (Watson API?)

Test-Driven Writing Process

Test-Driven Writing Process

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

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.

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.

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

Learning to Learn

Developers must be lifelong learners!

Learning to Learn

Developers must be lifelong learners!

Learning to learn process:

1. Set the state
2. Play
3. Reflect

Learning to Learn (continued...)

Learning to Learn (continued...)

(1) Set the Stage

Learning to Learn (continued...)

(1) Set the Stage

• Slow down, get your mind right

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

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?

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...)

Learning to Learn (continued...)

(2) Play

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.

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.

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.

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

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.

• 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

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.

• 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

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.

• 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

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.

• 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

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.

• 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?

Red

Red

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

Where do you start?

Red

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

Where do you start?

Red

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

Where do you start?

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

Red (continued...)

Red (continued...)

Who is your audience?

Red (continued...)

Who is your audience?

Put yourself in their shoes:

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

Red (continued...)

Who is your audience?

Put yourself in their shoes:

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

What kind of article do you want to write?

Red (continued...)

Who is your audience?

Put yourself in their shoes:

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

What kind of article do you want to write?

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

Red (continued...)

Red (continued...)

How does the article type affect the narrative?

Red (continued...)

How does the article type affect the narrative?

Narrative examples:

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

Red (continued...)

How does the article type affect the narrative?

Narrative examples:

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

What makes for a good objective?

Red (continued...)

How does the article type affect the narrative?

Narrative examples:

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

What makes for a good objective?

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

Green/Refactor

Green/Refactor

What's next?

Green/Refactor

What's next?

• Create a basic outline

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.

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

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

• Eliminate distractions
• Time-box yourself
• Try not to revise as you write (inspiration is fleeting!)
• Force yourself to step away
• Think about the length (shorter posts generally receive more comments, longer posts get more SEO love)

That's it!

That's it!

Additional Resources

1. Best Practices for Documenting Technical Procedures
2. What to Write
3. Write the Docs - Documentation Guide
4. Microsoft Style Guide
5. Google Developer Documentation Style Guide

That's it!

Additional Resources

1. Best Practices for Documenting Technical Procedures
2. What to Write
3. Write the Docs - Documentation Guide
4. Microsoft Style Guide
5. Google Developer Documentation Style Guide

Contact Info

1. michael@mherman.org
2. mherman.org
3. @mikeherman

That's it!

Additional Resources

1. Best Practices for Documenting Technical Procedures
2. What to Write
3. Write the Docs - Documentation Guide
4. Microsoft Style Guide
5. Google Developer Documentation Style Guide

Contact Info

1. michael@mherman.org
2. mherman.org
3. @mikeherman

Questions?

✌️