Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Thinking and Discovering by Writing

Thinking and Discovering by Writing


Stephen Mizell

November 17, 2015


  1. Thinking and Discovering by Writing Stephen Mizell

  2. What is the first thing you do when you start

    a project?
  3. Writing should be the first thing

  4. Think about what you're going to do before doing it

  5. Write about what you're going to do before doing it

  6. Writing Stages 4 Design 4 User Stories 4 Implementation 4

  7. Design

  8. Design the way the world works 4 "Design of Everyday

    Things" by Donald Norman 4 We know when something we encounter is wrong 4 "Norman Doors"
  9. None
  10. Write the way the world works

  11. Example: designing a door

  12. What did we design? 4 A physical door? 4 A

    door application? 4 A door API?
  13. State Machine with Affordances

  14. State Machine 4 States and affordances for designers to use

    4 Foundation for user stories to drive implementation 4 States and affordances to convey in API responses
  15. Ubiquitous Language

  16. Ubiquitous Language By using the model-based language pervasively and not

    being satisfied until it flows, we approach a model that is complete and comprehensible, made up of simple elements that combine to express complex ideas. — Eric Evans
  17. Ubiquitous Language Domain experts should object to terms or structures

    that are awkward or inadequate to convey domain understanding; developers should watch for ambiguity or inconsistency that will trip up design. — Eric Evans
  18. But naming is hard There are two hard things in

    computer science: cache invalidation, naming things, and off-by-one errors. — Jeff Atwood
  19. Summary on Writing for Design 4 Writing helps you think

    about design 4 Writing helps you surface a common vocabulary 4 Writing helps you understand the application's logic 4 Writing helps you have a discussion apart from implementation
  20. User Stories

  21. User Stories 4 Describes a user, what they want, and

    why 4 Captures a deliverable feature 4 Template for capturing simple requirements
  22. User Stories 4 Independent 4 Negotiable 4 Valuable 4 Estimatable

    4 Small 4 Testable From Write a Great User Story
  23. As a <role>, I want <goal> so that <benefit>

  24. Given... When... Then...

  25. Gherkin Feature: Lockable doors for users with keys As a

    door own I want to be able restrict access through the door So that I can secure my area Scenario: User with key encounters locked door Given I am a user with a key And I encounter a locked door When I try to unlock the door Then The door should be unlocked
  26. Summary on Writing User Stories 4 Capture small chunks of

    requirements 4 Understand logic and value added before implementation 4 Communicate with non-technical stakeholders
  27. Implementation

  28. Summary of Writing to Drive Implementation 4 Understand logic and

    vocabulary before coding 4 Defined scope of project requirements 4 Defined behavior to drive development
  29. Documentation

  30. Good Documentation 4 Introduction - General concept, feel, and understanding

    4 Explanation - How to actually use your project/ software 4 Reference - Reference material for drilling down 4 Troubleshooting - True frequently asked questions From How Great Documentation Drives Developer Adoption
  31. Documentation Practices 4 Readme Driven Development 4 Contract First 4

    Documentation lives alongside code 4 Documentation is generated from code 4 Documentation with Continuous Integration Build
  32. Documentation Tools 4 GitHub Pages and Jekyll 4 Literate Programming

    4 Read the Docs 4 Sphinx
  33. Summary of Writing Documentation 4 Provides help for your users

    4 Byproduct of good product design and implementation 4 Part of your deliverable to the end users
  34. References Writing 4 Markdown - for all kinds of writing

    4 API Blueprint - for APIs 4 Cucumber - for Gherkin 4 How to Write Well-Formed Stories
  35. References Software Architecture 4 Martin Fowler 4 Uncle Bob 4

    Ruby Midwest 2011 - Keynote: Architecture the Lost Years - Robert Martin
  36. References Documentation 4 Read the Docs 4 Sphinx 4 Jekyll

    4 How GitHub uses GitHub to document GitHub