ERD, Flowcharts and Other Documentation

Documentation is much more than just commenting on code. It can be a lot more fun, too. Learn what types of diagrams are useful, when and how to use them, and how it all ties into the development process. Through real-world examples, I will teach you how to create meaningful, helpful documentation not only for posterity but also to guide you in your development efforts.

Transcript

1. @afilina ERD, Flowcharts and Other Documentation DPC, Amsterdam - June 30, 2017
2. What It’s Not About • Not a full analysis and design course. • Not a demo of modelling tools. • Not a detailed explanation of symbology.
3. What It Is About • Which diagrams serve what purpose. • Tie diagrams together. • Real world examples.
4. Anna Filina • Project rescue expert • Dev, trainer, speaker
6. Why No Diagrams? • Don't know where to begin. • It's boring. • Get out of date. • Nobody reads them. • There’s no point. • Lean and mean.
7. Not Always Boring
8. The Real Problem • Don't understand diagrams. • Diagrams serve no purpose, not helpful. • Mistake diagrams for waterfall model. • Inadequate tools.
9. Conference Management Software
10. Use Case
11. Data Flow Diagram External entity
12. 1 2 3 4 5 6 7 8
13. Data Flow Diagram
14. Common Mistakes • Data not stored. • Black hole. • Grey hole. • Spontaneous generation.
15. Flowchart Input Output
16. Mockups
17. Mockups
18. ER Diagram 0 or more (many) 1
19. ER Diagram Non-identifying Identifying
20. ER Diagram
21. Behat Scenario: POST to /login endpoint with empty body When I send a POST request to "/login" with body: """ """ Then the response code should be 400
22. Source Comments • // Simple and short explanations. • /**
 * Document the "why" more than the "what".
 */ • Comment when it’s fresh. • Big functions with lots of comments = split function. • Better naming > comments.
23. Putting it All Together A.K.A. “The Manual”
24. Manual • Define chapters. Example: 1.Scope (Use Cases) 2.Database (ERD) 3.Processes (DFD + Flowchart) 4.Mockups (later screenshots) 5.Scenarios
25. Manual • Write topics in bullet point. • Add diagrams. • Write paragraph under each bullet. • Move topics and chapters around. • Fill in with details.
26. How Much to Write?
27. Application Complexity More docs Fewer docs Grandma’s recipes
 vs
 Facebook
28. Security Requirements Grandma’s recipes
 vs
 IAFIS fingerprints More docs Fewer docs
29. Financial Impact Grandma’s recipes
 vs
 Forex currency trading More docs Fewer docs
30. Team Size Yourself
 vs
 20 devs More docs Fewer docs
31. Team Proximity Same office
 vs
 Remote More docs Fewer docs
32. Developer Level Juniors
 vs
 Seniors More docs Fewer docs
33. Good Documentation • Makes your software easier to build and maintain. • Makes your team more effective. • Discover new scenarios or omissions before implementation.
34. Mind Maps Also Helpful Mind Maps
35. Takeaways • Systems Analysis and Design and/or UML book. • Get professional software, like Astah. • Diagrams are part of the process, not extra work. • Good diagrams increase dev speed and software quality.
36. @afilina afilina.com joind.in