Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Diagram Like a Principal Engineer

Diagram Like a Principal Engineer

What separates software engineers from principal software engineers? Mainly communication skills. One of the main communication skills in the principal engineer’s toolbelt is **diagramming**. In this session we’ll discuss different types of diagrams and their purposes. Then we’ll look at different tools we can use to make and share diagrams. Hopefully, we’ll all come out of this with a greater ability to draw boxes and arrows in a way that can bring about better software and teamwork and bigger paychecks.

Jeremy Lindblom

May 17, 2023
Tweet

More Decks by Jeremy Lindblom

Other Decks in Programming

Transcript

  1. Diagram Like A
    Principal Engineer
    by Jeremy Lindblom
    @jeremeamia

    View Slide

  2. 1. Principal Engineers
    Engineering across team boundaries

    View Slide

  3. $200k-$400k+
    “Total Compensation” includes
    all salary, bonuses, equity, stock,
    and benefits.
    3
    Potential Compensation
    Sources: levels.fyi and Glassdoor

    View Slide

  4. Software Engineer Leveling
    4
    JUNIOR
    SENIOR
    ⬗ Compensation is typically
    based on a predefined range
    for your level.

    View Slide

  5. Software Engineer Leveling
    5
    JUNIOR
    PRINCIPAL
    SENIOR

    View Slide

  6. Software Engineer Leveling
    6
    JUNIOR
    STAFF
    SENIOR
    PRINCIPAL

    View Slide

  7. Software Engineer Leveling
    7
    JUNIOR
    STAFF
    SENIOR
    PRINCIPAL
    JUNIOR
    PRINCIPAL
    SENIOR
    STAFF

    View Slide

  8. Software Engineer Leveling
    8
    DISTINGUISHED
    FELLOW
    JUNIOR
    STAFF
    SENIOR
    PRINCIPAL
    ⬗ No standards
    ⬗ Company-specific
    ⬗ Depends on company size

    View Slide

  9. Principles of a Principal
    1. Always Curious
    2. Good Communication
    3. Team Acceleration
    4. Inter-team Focus
    5. Engineering Experience
    9

    View Slide

  10. “The biggest issue on software
    teams is making sure
    everyone understands what
    everyone else is doing.”
    – Martin Fowler
    10

    View Slide

  11. Communication: Listen & Learn
    11
    ⬗ Customers
    ⬗ Company, orgs, & teams
    ⬗ Key people
    ⬗ Existing solutions
    ⬗ Current initiatives
    ⬗ Implementation details

    View Slide

  12. Communication: Give & Guide
    12
    ⬗ Share information & skills
    ⬗ Define problems & solutions
    ⬗ Create documentation & diagrams
    ⬗ Create interfaces & contracts
    ⬗ Connect people

    View Slide

  13. Principal Engineers…
    often serve as the
    “public API”
    for the orgs/teams
    they represent.
    13

    View Slide

  14. 14
    Don’t be a Gate.
    Be a Gateway.

    View Slide

  15. 2. Diagrams
    Boxes, lines, & arrows
    Boxes
    Arrows
    &

    View Slide

  16. 16
    What to Diagram?
    ⬗ Structures – Systems and components,
    AND their relationships, at various layers
    of abstraction
    ⬗ Behaviors – Processes, workflows,
    data flows, state machines, etc.

    View Slide

  17. 17
    When to Diagram?
    ⬗ Before implementation
    (Design ahead of projects and/or sprints)
    ⬗ During implementation
    (As part of a ticket or as things change)
    ⬗ After implementation
    (For documentation or onboarding)
    ANY TIME!

    View Slide

  18. 18
    How to Diagram?
    ⬗ Standards: UML, ERD, C4, etc., or ad hoc
    ⬗ Mediums: Pen/Marker vs. Computer
    ⬗ Method: Drawing vs. Coding

    View Slide

  19. Unified Modeling Language - UML
    1. Software industry standard
    2. Born in 1994 (Rational Software, now IBM)
    3. Plenty of tooling available
    19

    View Slide

  20. Unified Modeling Language - UML
    20

    View Slide

  21. 21

    View Slide

  22. 22
    Activity Diagrams
    ⬗ Workflows, actions, etc.
    ⬗ Supports conditional
    and parallel logic
    ⬗ Fairly easy to read,
    Even for non-tech

    View Slide

  23. 23
    Class Diagrams
    ⬗ Great for OOP, DB, and system design
    ⬗ Be as simple or detailed as you like
    ⬗ Focuses on relationships

    View Slide

  24. 24

    View Slide

  25. 25
    Class Diagrams - Entity Relationship Diagram (ERD)

    View Slide

  26. 26
    Sequence Diagrams
    ⬗ Implementation details
    ⬗ In reference to user
    ⬗ Shows e2e flow
    ⬗ Swimlanes can be classes,
    services, DBs, etc.

    View Slide

  27. 27
    Why Diagram?
    1. Improve development speed and quality
    Frontend developers use UI Mockups.
    Backend developers use UML diagrams.

    View Slide

  28. 28
    Why Diagram?
    2. You were asked to
    Sometimes other orgs (internal or external)
    want to see certain kinds of diagrams.
    💡 Tip: Know your audience.

    View Slide

  29. 29
    Why Diagram?
    3. Prevent catastrophe!
    Remove confusion and provide
    A well-defined goal.

    View Slide

  30. 30
    When I Should Have Diagrammed
    Lyrics by
    Jeremy Lindblom
    Original song by
    Bruno Mars
    “When I Was Your Man”

    View Slide

  31. 31
    Same code but it seems just a little bit brittle now.
    My commits in the git log, but it don’t look the same.
    When my team talks about it, all I do is just wonder how
    Nothing turned out how I planned it out in my brain🧠.

    View Slide

  32. 32
    It all just feels like foo— bar! 💩
    Mmm, too new, too junior to realize…

    View Slide

  33. 33
    That I should have diagrammed it, and shared the plan.
    Made sure we could understand it, before the work began.
    Showed you all my boxes📦 and arrows ⇄,
    so you could write a well-made program.
    Now there’s tech debt growing in a backlog without an end.

    View Slide

  34. 34
    How could’ve we developed this in such a silly way?
    I guess a sequence diagram or two would’ve helped us see.
    Now we’ll never, never get to clean up this mess we’ve made! Oh—.
    And that haunts👻 me every time I open my IDE.

    View Slide

  35. 35
    It all just feels like foo— bar! 💩
    Mmm, too new, too junior to realize…

    View Slide

  36. 36
    That I should have diagrammed it, and shared the plan.
    Made sure we could understand it, before the work began.
    Showed you all my boxes📦 and arrows ⇄,
    so you could write a well-made program.
    Now there’s tech debt growing in a backlog without an end.

    View Slide

  37. 37
    At our team retro—,
    I was the first to say that it’s all wrong—!
    But I know it’s probably much too late⏰,
    To refactor this code to make it all be great,
    So I just want you to know—.

    View Slide

  38. 38
    That I should have diagrammed it, and shared the plan.
    Made sure we could understand it, before the work began.
    Showed you all my boxes📦 and arrows ⇄,
    so you could write a well-made program.
    Now there’s tech debt growing in a backlog without an end.

    View Slide

  39. 39
    Yeah, just tech debt
    and groaning😩,
    because I didn’t diagram.

    View Slide

  40. 3.
    Diagramming Tools
    A step above pen and paper

    View Slide

  41. Types of Diagramming Tools
    Desktop Drawing
    (Visio, Rational Rose)
    Online Drawing
    (Lucid Chart, Miro, Gliffy, Diagrams.net)
    Code-based
    (Mermaid.js, PlantUML, yUML.me)
    41

    View Slide

  42. Mermaid.js
    “Mermaid lets you create
    diagrams and visualizations
    using text and code.”
    https://mermaid-js.github.io
    42

    View Slide

  43. Mermaid.js
    flowchart LR
    A((Start)) --> B[Call API]
    B --> C{Success?}
    C -->|Yes| D[Return Result]
    D --> E((End: Success))
    C -->|No| F{Too Many Attempts?}
    F -->|Yes| G((End: Error))
    F -->|No| H[Retry Call]
    H --> C
    43

    View Slide

  44. Selecting a Tool
    1. Collaboration (sharing, access, cost)
    2. Maintenance (keeping it up-to-date)
    3. Embeddability (in docs or repos)
    4. Customization
    5. Easy to Learn
    6. Usability
    44

    View Slide

  45. 45
    Let’s Draw Code!

    View Slide

  46. 46
    Thanks!
    Any questions?
    Jeremy Lindblom
    @jeremeamia

    View Slide