On writing promotion documents

The meatballs and gravy approach

(Like this article? Read more Wednesday Wisdom!)

T'is the season that giveth and the season that taketh: January has become the month of the year in which tech companies do layoffs and the month of the year in which tech companies do promotions. For some people, this will be a month to remember because they finally became senior principal underling and other people will remember it because they got laid off in order to ensure that somebody can have a second infinity pool installed in their third private jet.

There is a lot to say about the lay-offs, but by and large people are saying it, plus I am not quite ready to write about the lay-offs yet, with my own lay-off anniversary coming up in two days. So, I am going to keep it light and write about promotions instead; specifically about promotion documents.

If you are not yet ready for a promotion, but thinking about one, you might also want to read A Promotional Article.

During promotion season I typically read a large amount of very badly written promotion documents that try to explain why someone that I have typically not, or only tangentially, worked with is ready for promotion to the next level. In most cases, after reading the document, I still have no idea whether this candidate deserves to be promoted or not, which means the author completely failed to give a good picture of the candidate’s work.

Seen from class A airspace (18,000 - 60,000 feet, IFR required), writing a promotion document should be easy: Companies typically have role guidelines and so the “only” thing that needs to happen is explain to the reader how (note: “how”, not “that”) the candidate is fulfilling the requirements of the next level. Unfortunately, role guidelines are full of what Dutch lawyers call "open norms'', which is a nice technical term for vagueness. Open norms are open to interpretation; they do not specify in detail what the norm is.

Here is an example of an "open norm" from a role guideline: "The SDE42 is completing projects of deeper technical complexity than an SDE41 with only minimal guidance."

Open norms need to be operationalized: What does "deeper technical complexity" mean? If you look at a project, why is it of deeper technical complexity than another project? And what is "minimal guidance?" If the candidate has a weekly 1:1 with their technical lead on the project, is that minimal guidance, or maximal guidance? Does it matter what they talked about? Most promotion documents leave the reader to guess at that. This is a mistake because every reader will have their own definition of open norms. If the author explains how this project meets the “deeper technical complexity” requirement we can still have an argument about whether the project is sufficiently technically complicated, but at least then we are discussing tangible things.

There seems to be a crisis of writing going on because most promotion documents I see are outright terrible and a lot of them fail to get candidates promoted who might deserve it. A great promotion document might get an undeserving candidate promoted, but a bad promotion document will in almost all cases block a deserving candidate from being promoted.

Nothing beats a good writing course, but here are seven problems that I see in almost every promotion document:

1. Throwing the kitchen sink at the reader

One thing I regularly see is that the writer throws every little thing that the candidate has done into the document, relevant or not, leaving it to the reader to piece the evidence together from all of that detail. That's a terrible strategy that betrays the lack of a plan to convince the reader. This approach will make the promotion case hard to digest because there will be many things in the document that are not required to support a promotion and that muddles the waters because it gives the reader the idea that a lot of the candidate’s work was actually not worthy of promotion.

It is easiest if you can showcase all of the required behaviors in a small number of big projects. One of the things you typically need to show is depth of technical work, and that is hard to do if you refer to ten projects. There is always room for some small stuff to fill up the holes here and there, but that should be the coating on top of an otherwise great case.

I call this the "meatballs and gravy" approach: The meat balls are the big projects in which most of the behaviors required at the next level are showcased. The gravy then tops it off with things like interviews, oncall, code quality efforts and other nice things that display an overall senior and mature attitude to the job.

Like any good meatball dish, you don’t want to be hunting for the meatballs in the gravy! Don’t grind the meatballs and sprinkle the meat everywhere so that is hard to find.

2. Not making it clear what your team and service actually do (and why that is important)

All work is done in a context and to evaluate work correctly you need to know a bit about that context. Unfortunately, many promotion document authors seem to think that everyone knows the inside and outs of their services or team and write assuming that the reader already knows and understands their internal organization and technical architecture.

(Real) example: The FBOB service processes fareloads from ATPCO for QPX.

That’s awesome, as long as you know what ATPCO is, what QPX is, what fareloads are, and why this is important.

Promotion documents typically start with a description of the project and service, but writers often neglect to do that in a way that is accessible for readers outside of their immediate domain. Even very technical external readers (like me) often struggle to understand what it actually is they do over there, what the candidate’s role is, and why I should care.

Tip: To help promotion document writers I typically craft a standard paragraph introducing our team and our most important services in language that is targeted to impress promotion committees.

3. Statements instead of explanations

As I stated above, the role guidelines often contain open norms that need to be operationalized. Unfortunately, I see many promotion documents where the writer just copied the language from the guidelines without any explanation.

Example: X implemented multi-master replication for Spinach, which is very complicated.

I really have no idea whether this is in fact complicated or not, unless I know the ins and outs of the Spinach data store and all of the use cases around it. Setting up multi-master replication might be as simple as toggling a switch in the underlying data store configuration, or as complicated as developing lots of logic to deal with the consequences of out-of-order asynchronous replication.

Without any explanation, this sentence is an invitation to me to trust the writer in their judgment, which I typically don’t. Not because I am a distrusting curmudgeon (actually I am), but because I know that it is the author’s goal to convince me. If I would completely trust the author in their judgment, the entire promotion process would be unnecessary because they could just make the decision.

In a promotion document, don't tell me that something is complicated, explain to me how and why it is complicated.

In the same vein, if something was a lot of work, don't just say that it was a lot of work, but explain to me in what way it was a lot of work, for instance by pointing out that It needed three design docs, 50,000 lines of code, five releases, and the development of an entirely new 20-page runbook.

4. Missing links

If your promotion rationale references a design doc, link to it! Nerds like myself desperately want to look at these design docs to get an insight into the quantity and quality of the work. If you mention that the candidates wrote five postmortems, link to them. Same for code reviews, important tickets, and big Slack threads. If you mention that the candidate is the number one code reviewer in the team, link to a dashboard that shows that. 

The reader should really be able to validate the data underlying every claim in the document.

While we are on the topic of links: If you link to underlying collateral, make sure that every link serves its purpose. This means that it is accessible and impressive. You'd be surprised how often I click on a link in a promotion document only to be denied access. That is terrible because you have now missed an opportunity to give me data to support the promotion decision. It also reflects badly on the author of the document.

You also need to make sure that every link counts. I am not going to click on every link, so you need to make sure that every link I click on supports the story. For instance: If you include five links to code reviews and the first two I click on are one line config changes that seem totally obvious, I might not click on the other links and you have missed an opportunity to impress me with the work.

Do not bury the meat in the last link in the list. Do not include any non-impressive links in the list, lest someone click out of order. Make every link count!

5. Unquantified statements

Whenever you make a claim, add numbers to help the reader see that this was a big deal. If your promotion candidate is one of the top interviewers, provide stats on how many interviews they did and what the average feedback response time was. Same for the amount of tickets resolved and hours of oncall support completed. Do not use vague terms like "a lot" or "many” because these are totally meaningless and not convincing.

In general: Be very careful with adverbs and adjectives.

6. Connect to the role guidelines

Everything you write needs to be linked in some way to the role guidelines. Your job is to convince the reader that this candidate meets all of the requirements of working on the next level and so you need to make sure that you do that. Personally I am a big fan of the tabular approach, where you make a table that spells out all of the requirements of the role in the left column and then you write down the evidence for that behavior in the right column.

Even if your company’s promotion document style does not support including this table, you are well advised to make it to ensure that you have hit on all of the points.

Bonus points (from me) if you provide a link to the table :-)

Remember the “don’t state, explain” rule laid out above. If the role guidelines state that at the next level the candidate needs to showcase some behavior, don’t just say they did, but explain how they did that, preferably with links and numbers.

7. Write clearly

This is the hardest piece of advice because writing clearly is just so hard and I am very aware that it is even harder for non-idiomatic English speakers. 

A badly written document containing all the data can sink an otherwise unassailable promotion case. Your promotion document needs to take the reader by the hand and lead them to the inevitable conclusion that this person needs to be promoted because they are operating at the next level in their role. The reader will be skeptical and hence needs to be convinced with examples and data. For most companies the default decision is not to promote and so if you do not make the case, or make it badly, then the result will be a non-promotion.

Writing clearly is hard work and the only way to get any good at it is by doing it frequently and spending a lot of time on it. Write. Rewrite. Get feedback. Rewrite again. I am a decent and fast writer, and I typically spend 2-3 days on writing a promotion document and getting it right.

The worst promotion document is a missing one. Every season I wonder why some colleagues were not put up for promotion. In some cases the problem is that the promotion document is not yet ready, which is a planning problem. A promotion takes a year or so to prepare for and execute on. Start early!

A good strategy for explaining clearly what the promotion candidate has done is the STAR approach: Situation, Task, Action, Result. It works well for interviewing and it works well for promotions. Don’t be afraid to follow it.