BDD & Living Documentation

Talk given 7/12/2016 @ Write The Docs meetup at the New Relic office in Portland, OR.

Behavior Driven Development is a software methodology that uses natural language and concrete examples to understand exactly how features in your application should work. Focusing on meaningful team conversations and automated testing, BDD can provide up-to-date cliff notes on each part of your system. These principles encourage writing better user stories which will assist in a shared understanding of the underlying business goals. This in turn allows you to automate parts of your documentation and get an updated snapshot of the system on each build.

Speaker: Andy Craze is a left-handed, music obsessed, full-stack engineer with an interest in natural language. He currently writes code at Discogs and has also used BDD principles at Intel and Arizona State University. When he's not coding, he's either hiking around the Pacific Northwest or playing music with his friends.

Transcript

1. BDD & LIVING DOCS Andy Craze @accraze
2. Overview • BDD • Living Docs • Combination • Example • Questions?
3. BDD Buzzword Driven Development? Behavior Driven Development
4. Similar to TDD Test Driven Development But focused on cross-functional teams
5. Behavior Driven Development Business Goal Features Examples Executable Specifications Application Code Automated Acceptance Criteria • Tests • High level Documentation • Low-Level Documentation
6. Living Documentation • Code is single source of truth ◦ Extract the information you need. • Dynamically create self-documenting applications ◦ Generate static living docs site on each new build • Avoid documentation antipatterns: ◦ Redundant information ◦ Confusing brain dumps ◦ Misunderstood context
7. What should be documented? • Will it be of interest for a long period of time? • Will it be of interest to a large number of people? • Will it be considered critical or valuable?
8. Automated Docs Combo Business Goal Features Examples Executable Specifications Application Code BDD + Living Docs • Up-to-date info • See feature progress • Low-Level Documentation • Integration Testing Progress Reporting Living Docs Technical Docs Validation
9. Automated Docs Combo • Platform agnostic • Test Runner / Framework ◦ Example: Python - Behave • ‘Reporter’ to display results ◦ HTML, XML, Markdown, JSON, reStructuredText
10. Example Walkthrough • Feature: Logging In • Scenarios: User Logs in, Login Fail • Automated Steps: Entering Credentials, Find Auth message • Run Tests • Create living docs
11. Writing a Feature file Feature: Logging In As a user I would like to login to the site So I can see my information WHO WHAT WHY
12. Describe a scenario Scenario: User logs in Given I visit the site anonymously When I log in as a registered-user Then I should see the message “Welcome back!”
13. Describe another scenario Scenario: Login Fail Given I visit the site anonymously When I log in as an unregistered-user Then I should see the message “Please sign up”.
14. Describe syntax Scenario: <description> Given … setup When … action Then … result
15. Describe syntax Scenario: <description> Given ... When I enter my email address And I enter my password And I click the “Login” button
16. Executable Specification • Show your app’s expected behavior • Automate using Selenium Webdriver • Steps to define: ◦ User visits the site anonymously ◦ User logs in as "<username>" ◦ I should see the message <auth message>
17. Run Executable Specifications Fail First
18. Develop a Login Form
19. Key Benefits • Increased communication & efficiency ◦ Great for cross functional teams • Collaboration & iterative development. ◦ How well does your team work together? • High-level Docs, Low-Level Docs and Tests
20. Questions? accraze@gmail.com @accraze Blog: accraze.info