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.

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