ERD, Flowcharts and Other Documentation

ERD, Flowcharts and Other Documentation

Documentation is much more than just commenting code. It can be a lot more fun too. Learn what types of documentation are useful, when it is appropriate to use and how to write it. Through real-world examples, this talk will teach you how to create meaningful and helpful documentation.

B3b2139e4f2c0eca4efe2379fcebc1c5?s=128

Anna Filina

August 11, 2012
Tweet

Transcript

  1. FooLab ERD, Flowcharts and Other Documentation Northeast PHP Conference -

    August 11, 2012 Saturday, August 11, 2012
  2. FooLab What It’s Not About • Not a full analysis

    and design course • Not a demo of modeling tools • Not a detailed explanation of symbology 2 Saturday, August 11, 2012
  3. FooLab What It Is About • What diagrams serve what

    purpose • Tie diagrams together • Real world examples • More examples 3 Saturday, August 11, 2012
  4. FooLab Anna Filina • PHP Quebec - user group •

    ConFoo - non for profit Web conference • FooLab Inc. - IT consulting • I write code. • I train and supervise programmers. • I make recommendations. 4 Saturday, August 11, 2012
  5. FooLab Why No Docs? • Don't know where to begin

    • It's boring • There’s no point • Get out of date • Nobody reads them 5 Saturday, August 11, 2012
  6. FooLab The Real Problem • Don't understand diagrams • Diagrams

    serve no purpose, not helpful • Inadequate tools 6 Saturday, August 11, 2012
  7. FooLab Conference Management Software Saturday, August 11, 2012

  8. FooLab Use Case 8 Saturday, August 11, 2012

  9. FooLab ER Diagram 9 Saturday, August 11, 2012

  10. FooLab ER Diagram 9 0 or more (many) 1 Saturday,

    August 11, 2012
  11. FooLab ER Diagram 10 Saturday, August 11, 2012

  12. FooLab ER Diagram 10 Non-identifying Identifying Saturday, August 11, 2012

  13. FooLab ER Diagram 11 Saturday, August 11, 2012

  14. FooLab Data Flow Diagram 12 Saturday, August 11, 2012

  15. FooLab Data Flow Diagram 12 External entity Saturday, August 11,

    2012
  16. FooLab Data Flow Diagram 12 External entity Saturday, August 11,

    2012
  17. FooLab Data Flow Diagram 12 External entity Saturday, August 11,

    2012
  18. FooLab Data Flow Diagram 13 Saturday, August 11, 2012

  19. FooLab Data Flow Diagram 13 1 2 3 4 5

    6 7 8 Saturday, August 11, 2012
  20. FooLab Data Flow Diagram 14 Saturday, August 11, 2012

  21. FooLab Common Mistakes 15 • Data not stored. • Black

    hole. • Grey hole. • Spontaneous generation. Saturday, August 11, 2012
  22. FooLab Flowchart 16 Saturday, August 11, 2012

  23. FooLab Flowchart 16 Input Output Saturday, August 11, 2012

  24. FooLab Mockups 17 Saturday, August 11, 2012

  25. FooLab Mockups 18 Saturday, August 11, 2012

  26. FooLab Function Reference • Session • bool isSelected() • void

    mailConfirmation(), check logs • bool saveVote($user, $vote) • Automate tests of input/output. 19 Saturday, August 11, 2012
  27. FooLab Source Comments • Inline comments // simple and short

    explanations • /** * Commonly used above functions. * Can use annotations with phpDocumentor or other. */ Descriptive blocks • Comment when it’s fresh. • Big functions with lots of comments = split function. 20 Saturday, August 11, 2012
  28. FooLab Putting it all together A.K.A. “The Manual” Saturday, August

    11, 2012
  29. FooLab Manual • Define chapters. Example: 1. Scope (Use Cases)

    2. Database (ERD) 3. Processes (DFD + Flowchart) 4. Mockups (later screenshots) 5. Classes + usage 22 Saturday, August 11, 2012
  30. FooLab Manual • Write topics in bullet point • Add

    diagrams • Write paragraph under each bullet • Move topics and chapters around • Fill in with details 23 Saturday, August 11, 2012
  31. FooLab How much to write? Saturday, August 11, 2012

  32. FooLab Application Complexity 25 Grandma’s recipes vs Facebook Saturday, August

    11, 2012
  33. FooLab Application Complexity 25 More docs Less docs Grandma’s recipes

    vs Facebook Saturday, August 11, 2012
  34. FooLab Security Requirements 26 Grandma’s recipes vs IAFIS fingerprints Saturday,

    August 11, 2012
  35. FooLab Security Requirements 26 Grandma’s recipes vs IAFIS fingerprints More

    docs Less docs Saturday, August 11, 2012
  36. FooLab Financial Impact 27 Grandma’s recipes vs Forex currency trading

    Saturday, August 11, 2012
  37. FooLab Financial Impact 27 Grandma’s recipes vs Forex currency trading

    More docs Less docs Saturday, August 11, 2012
  38. FooLab Team Size 28 Yourself vs 20 devs Saturday, August

    11, 2012
  39. FooLab Team Size 28 Yourself vs 20 devs More docs

    Less docs Saturday, August 11, 2012
  40. FooLab Team Proximity 29 Same office vs Remote Saturday, August

    11, 2012
  41. FooLab Team Proximity 29 Same office vs Remote More docs

    Less docs Saturday, August 11, 2012
  42. FooLab Good Documentation • Makes your software easier to build

    and maintain • Makes your team more effective • Discover new features before implementation 30 Saturday, August 11, 2012
  43. FooLab Mind Maps Saturday, August 11, 2012

  44. FooLab Systems Analysis and Design and/or UML book Saturday, August

    11, 2012
  45. FooLab Next Steps • I will tweet the slides: @afilina

    • Please leave feedback: http://joind.in/6838 33 Saturday, August 11, 2012
  46. FooLab Ask me which software I use. Saturday, August 11,

    2012
  47. FooLab Ask me which software I use. astah, Balsamiq Saturday,

    August 11, 2012