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
2. 1. Principal Engineers Engineering across team boundaries
3. $200k-$400k+ “Total Compensation” includes all salary, bonuses, equity, stock, and benefits. 3 Potential Compensation Sources: levels.fyi and Glassdoor
4. Software Engineer Leveling 4 JUNIOR SENIOR ⬗ Compensation is typically based on a predefined range for your level.
5. Software Engineer Leveling 5 JUNIOR PRINCIPAL SENIOR
6. Software Engineer Leveling 6 JUNIOR STAFF SENIOR PRINCIPAL
7. Software Engineer Leveling 7 JUNIOR STAFF SENIOR PRINCIPAL JUNIOR PRINCIPAL SENIOR STAFF
8. Software Engineer Leveling 8 DISTINGUISHED FELLOW JUNIOR STAFF SENIOR PRINCIPAL ⬗ No standards ⬗ Company-specific ⬗ Depends on company size
9. Principles of a Principal 1. Always Curious 2. Good Communication 3. Team Acceleration 4. Inter-team Focus 5. Engineering Experience 9
10. “The biggest issue on software teams is making sure everyone understands what everyone else is doing.” – Martin Fowler 10
11. Communication: Listen & Learn 11 ⬗ Customers ⬗ Company, orgs, & teams ⬗ Key people ⬗ Existing solutions ⬗ Current initiatives ⬗ Implementation details
12. Communication: Give & Guide 12 ⬗ Share information & skills ⬗ Define problems & solutions ⬗ Create documentation & diagrams ⬗ Create interfaces & contracts ⬗ Connect people
13. Principal Engineers… often serve as the “public API” for the orgs/teams they represent. 13
14. 14 Don’t be a Gate. Be a Gateway.
15. 2. Diagrams Boxes, lines, & arrows Boxes Arrows &
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.
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!
18. 18 How to Diagram? ⬗ Standards: UML, ERD, C4, etc., or ad hoc ⬗ Mediums: Pen/Marker vs. Computer ⬗ Method: Drawing vs. Coding
19. Unified Modeling Language - UML 1. Software industry standard 2. Born in 1994 (Rational Software, now IBM) 3. Plenty of tooling available 19
20. Unified Modeling Language - UML 20
22. 22 Activity Diagrams ⬗ Workflows, actions, etc. ⬗ Supports conditional and parallel logic ⬗ Fairly easy to read, Even for non-tech
23. 23 Class Diagrams ⬗ Great for OOP, DB, and system design ⬗ Be as simple or detailed as you like ⬗ Focuses on relationships
25. 25 Class Diagrams - Entity Relationship Diagram (ERD)
26. 26 Sequence Diagrams ⬗ Implementation details ⬗ In reference to user ⬗ Shows e2e flow ⬗ Swimlanes can be classes, services, DBs, etc.
27. 27 Why Diagram? 1. Improve development speed and quality Frontend developers use UI Mockups. Backend developers use UML diagrams.
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.
29. 29 Why Diagram? 3. Prevent catastrophe! Remove confusion and provide A well-defined goal.
30. 30 When I Should Have Diagrammed Lyrics by Jeremy Lindblom Original song by Bruno Mars “When I Was Your Man”
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🧠.
32. 32 It all just feels like foo— bar! 💩 Mmm, too new, too junior to realize…
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.
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.
35. 35 It all just feels like foo— bar! 💩 Mmm, too new, too junior to realize…
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.
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—.
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.
39. 39 Yeah, just tech debt and groaning😩, because I didn’t diagram.
40. 3. Diagramming Tools A step above pen and paper
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
42. Mermaid.js “Mermaid lets you create diagrams and visualizations using text and code.” https://mermaid-js.github.io 42
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
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
45. 45 Let’s Draw Code!
46. 46 Thanks! Any questions? Jeremy Lindblom @jeremeamia