Issue 13 - Diagrams as Code and a Model for Self-Evaluations

We’re one month into the new year, and for many, that means annual review time. I’m preparing for it myself, writing my self-evaluation, an evaluation for my manager, and evaluations for the team I support. This month I want to share the model I use to do my self-evaluation and make sure I don’t leave certain things out.

I also want to show you a tool that’s helpful for both content creators and software developers that lets you create diagrams using a plain text markup language.

Let’s dive in.

Build a Strong Self-Evaluation

It’s performance review season where I work, and part of the process involves writing a self-evaluation. For many, writing the self-evaluation is one of the trickiest parts of the process. Some people find it hard to talk about themselves. Others don’t spend the time to do the deep reflection that will help them grow.

A good self-evaluation covers the highs, the lows, the challenges, and the opportunities ahead. I have a model I follow for my evaluations, and I think it’ll help you too.

Here’s what you should try in your self-evaluation:

Accomplishments

Highlight significant projects and initiatives you led or contributed to and their impact on the company or department. Be specific. Your manager isn’t going to remember everything you did, so you’ll have to remind them. This is where you have to sell yourself, but it’s also where you’ll show that you worked on the right things that contributed to the business. This is where you talk about the things you shipped and the impact they had. And if you can’t talk about that because you don’t know, then you’ve just uncovered one reason to do a self-evaluation: to surface things you’ll want to address with your manager.

Goals and Objectives

Reflect on the goals and objectives you set for yourself since the last review cycle and how you performed against them. While you may not have met every goal you wanted to, be sure to call out the goals you completed and the ones you exceeded. Own both the good and the bad.

Opportunities for Improvement

Identify situations where you could have performed better, what you learned from your mistakes, and how you plan to improve. We all have areas for improvement; this is another place you’ll want to be specific. Show that you’re learning and growing, and that you want to get better. And between review cycles, figure out where you need to catch up by soliciting feedback from others. Don’t just wait for review time to do this work.

Collaboration and Communication

Describe your ability to work effectively with others, both within your department and cross-functionally, as well as your communication style and effectiveness. Again here, be specific. Share situations where you provided feedback, incorporated feedback from others, or how you teamed up with someone in another area to accomplish a goal. If you’re struggling to find examples of how you collaborate and communicate with others, you may be too isolated. Collaboration is how we move big things forward. Show that you’re a part of that.

Challenges and Obstacles

Share challenges you faced during the year. Explain what you did to overcome them and what you learned from the experience. Show off your problem-solving skills here. You could talk about a communication problem you had to push through or something technical you had to overcome. Perhaps you had to learn a new role. Show off your problem-solving skills.

Future Focus

Outline your priorities for the next six months and any initiatives or projects you plan to take on, or identify places where you’d like to contribute more. This is your chance to help steer the direction of your career. Take the initiative to put some ideas forward rather than wait for someone to hand you things to do.

Feedback You’ve Received

Include feedback from others, such as team members or peers across the org, to provide a well-rounded view of your performance. Many places do formal feedback reviews, but it’s worth soliciting feedback throughout the year from others that you can include in your self-evaluation, especially if it was feedback that helped you improve.

Bonus: Leadership and Management

If you lead people, evaluate your leadership and management style. Discuss what worked well and what you could improve. Identify some areas where you could have pushed a little harder, but also be sure to point out where you made a positive contribution to your team’s work. Your job as a leader is to be a force multiplier. Show how you do that.

Some of these points may overlap. You might talk about some feedback you received as part of your accomplishments or your collaboration with others. This list is more like a checklist of things you should cover rather than a prescriptive formula you should follow.

If you cover each of these areas in detail, you’ll have a solid self-evaluation, and you’ll also have a more clear picture of your performance and progress. Then, as you move into the next cycle, keep this list handy and see if you can fill it out as you go. Keep getting feedback from others, keep collaborating, and most of all, keep track of your wins throughout the year. Remembering everything that happened at the end of the year is a lot of work. Be proactive and use this model to turn self-evaluations into self-reflection. Next year you’ll have your entire evaluation done in no time.

Create Diagrams with Mermaid

Mermaid is a diagramming tool that lets you create diagrams using plain text. I fell in love with this tool when it first came out, and it’s a part of my documentation workflow. I’m surprised that more people don’t know about it, but it looks like it’s finally gaining popularity. Obsidian and Notion support Mermaid diagrams, and so does my favorite Markdown editor, Typora. In fact, with Typora, I can create diagrams in my Markdown documentation and export them to PDF files without using any extra tooling.

Mermaid lets you create flowcharts, sequence diagrams, pie charts, user journeys, and much more, using plain-text diagram definitions that are fairly readable.

Here’s an example of a sequence diagram from their documentation:

sequenceDiagram
   Alice->>John: Hello John, how are you?
   John-->>Alice: Great!
   Alice-)John: See you later!

In this diagram, you can see the interactions between Alice and John. The ->> symbol draws a closed arrow, while -) draws an open arrow, so you can represent synchronous and asynchronous messages in your diagram.

A pie chart in Mermaid is even more intuitive. Here’s an example from the documentation:

pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

The pie chart renders with a legend and the percentages.

You can customize these diagrams with CSS and embed them in your web pages if you add the Mermaid client-side JavaScript library.

You can also use mermaid-cli to convert a Mermaid diagram to an SVG file too, which you could then embed directly into the document.

Mermaid isn’t perfect in all situations, but it’s fantastic for creating quick diagrams in Notion pages or Obsidian docs, and it’s an excellent tool for creating a quick sketch of a diagram that you could then recreate in an illustration tool.

If you want to learn more, check out the book Creating Software with Modern Diagramming Techniques by Ashley Peacock, and play around with Mermaid.live, an in-browser editor. And, of course, there’s the Mermaid documentation.

Parting Thoughts

As always, thanks for reading this month’s issue. If you liked what you saw, please share it with others through email or social media.

Before moving on, work through the following prompts:

1. Reflect on the last year, or at least since the last time you had a performance review. What were those significant accomplishments? If you had a review next week, how much of the self-evaluation model could you fill out? If it’s a challenge, that’s your cue to figure out how to start keeping better track of your wins and losses.
2. Use Mermaid.live and create your own pie chart and sequence diagram. Then create a flow chart that shows how a request makes its way from a browser to a web server.

I'd love to talk with you about this newsletter on Mastodon, Twitter, or LinkedIn. Let's connect!

Please support this newsletter and my work by encouraging others to subscribe or by buying a friend a copy of Exercises for Programmers, Small, Sharp Software Tools, or any of my other books.