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
Tweet

More Decks by Stephen Mizell

Other Decks in Programming

Transcript

  1. 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"
  2. What did we design? 4 A physical door? 4 A

    door application? 4 A door API?
  3. 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
  4. 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
  5. 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
  6. But naming is hard There are two hard things in

    computer science: cache invalidation, naming things, and off-by-one errors. — Jeff Atwood
  7. 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
  8. User Stories 4 Describes a user, what they want, and

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

    4 Small 4 Testable From Write a Great User Story
  10. 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
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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
  16. 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
  17. References Software Architecture 4 Martin Fowler 4 Uncle Bob 4

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

    4 How GitHub uses GitHub to document GitHub