Lock in $30 Savings on PRO—Offer Ends Soon! ⏳

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. $200k-$400k+ “Total Compensation” includes all salary, bonuses, equity, stock, and

    benefits. 3 Potential Compensation Sources: levels.fyi and Glassdoor
  2. Software Engineer Leveling 8 DISTINGUISHED FELLOW JUNIOR STAFF SENIOR PRINCIPAL

    ⬗ No standards ⬗ Company-specific ⬗ Depends on company size
  3. Principles of a Principal 1. Always Curious 2. Good Communication

    3. Team Acceleration 4. Inter-team Focus 5. Engineering Experience 9
  4. “The biggest issue on software teams is making sure everyone

    understands what everyone else is doing.” – Martin Fowler 10
  5. Communication: Listen & Learn 11 ⬗ Customers ⬗ Company, orgs,

    & teams ⬗ Key people ⬗ Existing solutions ⬗ Current initiatives ⬗ Implementation details
  6. Communication: Give & Guide 12 ⬗ Share information & skills

    ⬗ Define problems & solutions ⬗ Create documentation & diagrams ⬗ Create interfaces & contracts ⬗ Connect people
  7. 16 What to Diagram? ⬗ Structures – Systems and components,

    AND their relationships, at various layers of abstraction ⬗ Behaviors – Processes, workflows, data flows, state machines, etc.
  8. 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!
  9. 18 How to Diagram? ⬗ Standards: UML, ERD, C4, etc.,

    or ad hoc ⬗ Mediums: Pen/Marker vs. Computer ⬗ Method: Drawing vs. Coding
  10. Unified Modeling Language - UML 1. Software industry standard 2.

    Born in 1994 (Rational Software, now IBM) 3. Plenty of tooling available 19
  11. 21

  12. 22 Activity Diagrams ⬗ Workflows, actions, etc. ⬗ Supports conditional

    and parallel logic ⬗ Fairly easy to read, Even for non-tech
  13. 23 Class Diagrams ⬗ Great for OOP, DB, and system

    design ⬗ Be as simple or detailed as you like ⬗ Focuses on relationships
  14. 24

  15. 26 Sequence Diagrams ⬗ Implementation details ⬗ In reference to

    user ⬗ Shows e2e flow ⬗ Swimlanes can be classes, services, DBs, etc.
  16. 27 Why Diagram? 1. Improve development speed and quality Frontend

    developers use UI Mockups. Backend developers use UML diagrams.
  17. 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.
  18. 30 When I Should Have Diagrammed Lyrics by Jeremy Lindblom

    Original song by Bruno Mars “When I Was Your Man”
  19. 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🧠.
  20. 32 It all just feels like foo— bar! 💩 Mmm,

    too new, too junior to realize…
  21. 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.
  22. 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.
  23. 35 It all just feels like foo— bar! 💩 Mmm,

    too new, too junior to realize…
  24. 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.
  25. 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—.
  26. 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.
  27. 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
  28. 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
  29. 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