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
   

   View 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 Slide

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

   View Slide

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

   View Slide

5. View Slide

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
   

   View Slide

7. Not Always Boring
   7
   

   View Slide

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

   View Slide

9. Conference
   Management
   Software
   

   View Slide

10. Use Case
    10
    

    View Slide

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

    View Slide

12. ER Diagram
    12
    Non-identifying
    Identifying
    

    View Slide

13. ER Diagram
    13
    

    View Slide

14. Data Flow Diagram
    14
    External entity
    

    View Slide

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

    View Slide

16. Data Flow Diagram
    16
    

    View Slide

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

    View Slide

18. Flowchart
    18
    Input
    Output
    

    View Slide

19. Mockups
    19
    

    View Slide

20. Mockups
    20
    

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

26. How Much to Write?
    

    View Slide

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

    vs
 Facebook
    

    View Slide

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

    vs

    IAFIS
    fingerprints
    

    View Slide

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

    vs

    Forex
    currency
    trading
    

    View Slide

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

    View Slide

31. Team Proximity
    31
    More docs
    Less docs
    Same
    office

    vs
 Remote
    

    View Slide

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

    View Slide

33. FooLab
    Mind Maps
    

    View Slide

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
    

    View Slide

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

    View Slide

36. @afilina afilina.com
    joind.in
    

    View Slide