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. @afilina
   ERD, Flowcharts and
   Other Documentation
   NWVDNUG - March 22, 2017
   

   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.
   

   View Slide

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

   View Slide

4. Anna Filina
   • Project rescue expert
   • Dev, trainer, speaker
   • 1 company
   • 2 conferences
   

   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.
   

   View Slide

7. Not Always Boring
   

   View Slide

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

   View Slide

9. Conference
   Management
   

   View Slide

10. Use Case
    

    View Slide

11. ER Diagram
    0 or more
    (many)
    1
    

    View Slide

12. ER Diagram
    Non-identifying
    Identifying
    

    View Slide

13. ER Diagram
    

    View Slide

14. Data Flow Diagram
    External entity
    

    View Slide

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

    View Slide

16. Data Flow Diagram
    

    View Slide

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

    View Slide

18. Flowchart
    Input
    Output
    

    View Slide

19. Mockups
    

    View Slide

20. Mockups
    

    View Slide

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

    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.
    

    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
    

    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.
    

    View Slide

26. How Much to Write?
    

    View Slide

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

    vs
 Facebook
    

    View Slide

28. Security Requirements
    Grandma’s
    recipes

    vs

    IAFIS
    fingerprints
    More docs
    Less docs
    

    View Slide

29. Financial Impact
    Grandma’s
    recipes

    vs

    Forex
    currency
    trading
    More docs
    Less docs
    

    View Slide

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

    View Slide

31. Team Proximity
    Same
    office

    vs
 Remote
    More docs
    Less docs
    

    View Slide

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

    View Slide

33. Mind Maps Also
    Helpful
    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.
    

    View Slide

35. @afilina afilina.com
    

    View Slide