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. Not just for posterity, but to guide you in your development efforts.

B3b2139e4f2c0eca4efe2379fcebc1c5?s=128

Anna Filina

August 25, 2012
Tweet

Transcript

  1. FooLab ERD, Flowcharts and Other Documentation FrOSCon - August 25,

    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
  3. FooLab What It Is About • What diagrams serve what

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

    ConFoo - non for profit Web conference • FooLab Inc. • I write code. • I train and supervise programmers. 4
  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 • Lean and mean 5
  6. FooLab Not Always Boring 6

  7. FooLab The Real Problem • Don't understand diagrams • Diagrams

    serve no purpose, not helpful • Mistake diagrams for waterfall model • Inadequate tools 7
  8. FooLab Conference Management Software

  9. FooLab Use Case 9

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

  11. FooLab ER Diagram 11 Non-identifying Identifying

  12. FooLab ER Diagram 12

  13. FooLab Data Flow Diagram 13 External entity

  14. FooLab Data Flow Diagram 14 1 2 3 4 5

    6 7 8
  15. FooLab Data Flow Diagram 15

  16. FooLab Common Mistakes 16 • Data not stored. • Black

    hole. • Grey hole. • Spontaneous generation.
  17. FooLab Flowchart 17 Input Output

  18. FooLab Mockups 18

  19. FooLab Mockups 19

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

    mailConfirmation(), check logs • bool saveVote($user, $vote) • Automate tests of input/output. 20
  21. 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. 21
  22. FooLab Putting it all together A.K.A. “The Manual”

  23. FooLab Manual • Define chapters. Example: 1. Scope (Use Cases)

    2. Database (ERD) 3. Processes (DFD + Flowchart) 4. Mockups (later screenshots) 5. Classes + usage 23
  24. FooLab Manual • Write topics in bullet point • Add

    diagrams • Write paragraph under each bullet • Move topics and chapters around • Fill in with details 24
  25. FooLab How much to write?

  26. FooLab Application Complexity 26 More docs Less docs Grandma’s recipes

    vs Facebook
  27. FooLab Security Requirements 27 Grandma’s recipes vs IAFIS fingerprints More

    docs Less docs
  28. FooLab Financial Impact 28 Grandma’s recipes vs Forex currency trading

    More docs Less docs
  29. FooLab Team Size 29 Yourself vs 20 devs More docs

    Less docs
  30. FooLab Team Proximity 30 Same office vs Remote More docs

    Less docs
  31. FooLab Good Documentation • Makes your software easier to build

    and maintain • Makes your team more effective • Discover new features before implementation 31
  32. FooLab Mind Maps

  33. FooLab Systems Analysis and Design and/or UML book

  34. FooLab Next Steps • I will tweet the slides: @afilina

    • Please leave feedback: http://bit.ly/anna-docs 34
  35. FooLab Ask me which software I use. astah, Balsamiq