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 documentation are useful, when it is appropriate to use documentation, and how to write it. 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. foolab.ca | @foolabca ERD, Flowcharts and Other Documentation php[tek], St. Louis - May 25, 2016
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. 2
3. What It Is About • Which diagrams serve what purpose. • Tie diagrams together. • Real world examples. 3
4. Anna Filina • Developer • Problem solver • Teacher • Advisor • FooLab + ConFoo 4
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. 6
7. Not Always Boring 7
8. The Real Problem • Don't understand diagrams. • Diagrams serve no purpose, not helpful. • Mistake diagrams for waterfall model. • Inadequate tools. 8
9. Conference Management Software
10. Use Case 10
11. ER Diagram 11 0 or more (many) 1
12. ER Diagram 12 Non-identifying Identifying
13. ER Diagram 13
14. Data Flow Diagram 14 External entity
15. Data Flow Diagram 15 1 2 3 4 5 6 7 8
16. Data Flow Diagram 16
17. Common Mistakes • Data not stored. • Black hole. • Grey hole. • Spontaneous generation. 17
18. Flowchart 18 Input Output
19. Mockups 19
20. Mockups 20
21. Function Reference • Session ◦ bool isSelected() ◦ void mailConfirmation(), check logs ◦ bool saveVote($user, $vote) • Automate tests of input/output. 21
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. 22
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.Classes + usage 24
25. Manual • Write topics in bullet point. • Add diagrams. • Write paragraph under each bullet. • Move topics and chapters around. • Fill in with details. 25
26. How Much to Write?
27. Application Complexity 27 More docs Less docs Grandma’s recipes
 vs
 Facebook
28. Security Requirements 28 More docs Less docs Grandma’s recipes
 vs
 IAFIS fingerprints
29. Financial Impact 29 More docs Less docs Grandma’s recipes
 vs
 Forex currency trading
30. Team Size 30 More docs Less docs Yourself
 vs
 20 devs
31. Team Proximity 31 More docs Less docs Same office
 vs
 Remote
32. Good Documentation • Makes your software easier to build and maintain. • Makes your team more effective. • Discover new features before implementation. 32
33. FooLab Mind Maps
34. 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. 34
35. Anna Filina • Development. • Fix bugs & performance issues. • Workshops on testing, frameworks & APIs. • Advisor on testing strategy, legacy code. 35
36. @afilina afilina.com joind.in