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

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

    View full-size slide

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

    View full-size slide

  4. Anna Filina
    • Project rescue expert
    • Dev, trainer, speaker

    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.

    View full-size slide

  6. Not Always Boring

    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.

    View full-size slide

  8. Conference
    Management Software

    View full-size slide

  9. Data Flow Diagram
    External entity

    View full-size slide

  10. 1 2 3 4 5 6
    7 8

    View full-size slide

  11. Data Flow Diagram

    View full-size slide

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

    View full-size slide

  13. Flowchart
    Input
    Output

    View full-size slide

  14. ER Diagram
    0 or more
    (many)
    1

    View full-size slide

  15. ER Diagram
    Non-identifying
    Identifying

    View full-size slide

  16. 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 full-size slide

  17. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  21. How Much to Write?

    View full-size slide

  22. Application Complexity
    More docs
    Fewer docs
    Grandma’s
    recipes

    vs
 Facebook

    View full-size slide

  23. Security Requirements
    Grandma’s
    recipes

    vs

    IAFIS
    fingerprints
    More docs
    Fewer docs

    View full-size slide

  24. Financial Impact
    Grandma’s
    recipes

    vs

    Forex
    currency
    trading
    More docs
    Fewer docs

    View full-size slide

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

    View full-size slide

  26. Team Proximity
    Same
    office

    vs
 Remote
    More docs
    Fewer docs

    View full-size slide

  27. Developer Level
    Juniors
 vs
 Seniors
    More docs
    Fewer docs

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  31. @afilina afilina.com
    joind.in

    View full-size slide