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

Anna Filina
PRO

June 30, 2017
Tweet

More Decks by Anna Filina

Other Decks in Programming

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