Thinking and Discovering by Writing

Transcript

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 Documentation
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"
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