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 diagrams are useful, when and how to use them, and how it all ties into the development process. 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
   DPC, Amsterdam - June 30, 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
   

   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 Software
   

   View Slide

10. Use Case
    

    View Slide

11. Data Flow Diagram
    External entity
    

    View Slide

12. 1 2 3 4 5 6
    7 8
    

    View Slide

13. Data Flow Diagram
    

    View Slide

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

    View Slide

15. Flowchart
    Input
    Output
    

    View Slide

16. Mockups
    

    View Slide

17. Mockups
    

    View Slide

18. ER Diagram
    0 or more
    (many)
    1
    

    View Slide

19. ER Diagram
    Non-identifying
    Identifying
    

    View Slide

20. ER Diagram
    

    View Slide

21. Behat
    Scenario: POST to /login endpoint with empty body
    When I send a POST request to "/login" with body:
    """
    """
    Then the response code should be 400
    

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

    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
    Fewer docs
    Grandma’s
    recipes

    vs
 Facebook
    

    View Slide

28. Security Requirements
    Grandma’s
    recipes

    vs

    IAFIS
    fingerprints
    More docs
    Fewer docs
    

    View Slide

29. Financial Impact
    Grandma’s
    recipes

    vs

    Forex
    currency
    trading
    More docs
    Fewer docs
    

    View Slide

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

    View Slide

31. Team Proximity
    Same
    office

    vs
 Remote
    More docs
    Fewer docs
    

    View Slide

32. Developer Level
    Juniors
 vs
 Seniors
    More docs
    Fewer docs
    

    View Slide

33. Good Documentation
    • Makes your software easier to build and
    maintain.
    • Makes your team more effective.
    • Discover new scenarios or omissions
    before implementation.
    

    View Slide

34. Mind Maps Also
    Helpful
    Mind Maps
    

    View Slide

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

36. @afilina afilina.com
    joind.in
    

    View Slide