Upgrade to Pro — share decks privately, control downloads, hide ads and more …

ERD, Flowcharts and Other Documentation

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.

Anna Filina

May 25, 2016
Tweet

More Decks by Anna Filina

Other Decks in Programming

Transcript

  1. foolab.ca | @foolabca
    ERD, Flowcharts and
    Other Documentation
    php[tek], St. Louis - May 25, 2016

    View full-size slide

  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

    View full-size slide

  3. What It Is About
    • Which diagrams serve what
    purpose.
    • Tie diagrams together.
    • Real world examples.
    3

    View full-size slide

  4. Anna Filina
    • Developer
    • Problem solver
    • Teacher
    • Advisor
    • FooLab + ConFoo
    4

    View full-size slide

  5. 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

    View full-size slide

  6. Not Always Boring
    7

    View full-size slide

  7. The Real Problem
    • Don't understand diagrams.
    • Diagrams serve no purpose, not helpful.
    • Mistake diagrams for waterfall model.
    • Inadequate tools.
    8

    View full-size slide

  8. Conference
    Management
    Software

    View full-size slide

  9. ER Diagram
    11
    0 or more
    (many)
    1

    View full-size slide

  10. ER Diagram
    12
    Non-identifying
    Identifying

    View full-size slide

  11. ER Diagram
    13

    View full-size slide

  12. Data Flow Diagram
    14
    External entity

    View full-size slide

  13. Data Flow Diagram
    15
    1 2 3 4 5 6
    7
    8

    View full-size slide

  14. Data Flow Diagram
    16

    View full-size slide

  15. Common Mistakes
    • Data not stored.
    • Black hole.
    • Grey hole.
    • Spontaneous generation.
    17

    View full-size slide

  16. Flowchart
    18
    Input
    Output

    View full-size slide

  17. Function Reference
    • Session
    ◦ bool isSelected()
    ◦ void mailConfirmation(), check logs
    ◦ bool saveVote($user, $vote)
    • Automate tests of input/output.
    21

    View full-size slide

  18. 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

    View full-size slide

  19. Putting it All Together
    A.K.A. “The Manual”

    View full-size slide

  20. Manual
    • Define chapters. Example:
    1.Scope (Use Cases)
    2.Database (ERD)
    3.Processes (DFD + Flowchart)
    4.Mockups (later screenshots)
    5.Classes + usage
    24

    View full-size slide

  21. Manual
    • Write topics in bullet point.
    • Add diagrams.
    • Write paragraph under each bullet.
    • Move topics and chapters around.
    • Fill in with details.
    25

    View full-size slide

  22. How Much to Write?

    View full-size slide

  23. Application Complexity
    27
    More docs
    Less docs
    Grandma’s
    recipes

    vs
 Facebook

    View full-size slide

  24. Security Requirements
    28
    More docs
    Less docs
    Grandma’s
    recipes

    vs

    IAFIS
    fingerprints

    View full-size slide

  25. Financial Impact
    29
    More docs
    Less docs
    Grandma’s
    recipes

    vs

    Forex
    currency
    trading

    View full-size slide

  26. Team Size
    30
    More docs
    Less docs
    Yourself
 vs
 20 devs

    View full-size slide

  27. Team Proximity
    31
    More docs
    Less docs
    Same
    office

    vs
 Remote

    View full-size slide

  28. Good Documentation
    • Makes your software easier to build and maintain.
    • Makes your team more effective.
    • Discover new features before implementation.
    32

    View full-size slide

  29. FooLab
    Mind Maps

    View full-size slide

  30. 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

    View full-size slide

  31. Anna Filina
    • Development.
    • Fix bugs & performance issues.
    • Workshops on testing, frameworks & APIs.
    • Advisor on testing strategy, legacy code.
    35

    View full-size slide

  32. @afilina afilina.com
    joind.in

    View full-size slide