The Developer Advocacy Handbook

If you find this helpful, you can buy me a coffee.

Work with your own company

Chris Heilmann looking up at the Microsoft logo

As a developer advocate you will find that a large part of your work is dealing with internal colleagues and unpredictable changes to your company.

This can actually be a much harder job than dealing with the outside. The reason is that people on the inside have both more information about and a different relationship to the products you advocate.

That can mean that whilst the outside world is excited about a certain product, people on the inside aren’t proud of it at all. And getting praise for a job you considered not done well isn’t a good feeling. It makes you feel like people don’t appreciate your efforts at all.

The journey towards releasing a product can be painful, frustrating and sometimes plain confusing. For example, highly successful products can bleed money. That could lead to a lot of frustration in the company as other, more lucrative or efficient products don’t get the same resources.

Your job as a developer advocate is to listen to people on the inside, understand their problems and communicate with management to try and fix these issues. You also need to ensure that you remind people of facts instead of chiming in with bad rumours. What the outside world says about the company and products might not necessarily be the real picture.

Frustrated people are likely to say bad things about their company on social media and elsewhere. That isn’t only a problem for your products but could also be a bad move for their career. Often you will find yourself being a sounding board for the frustrations of the people building products and a mentor to keep them from saying things publicly they may regret later. It is important to build up a reputation as someone people can vent at about their work without repercussions. This also is an important step to validate the worth of the developer advocate position to developers. After all, you are their advocate, right?

Tip: Seeing a tech company fail is an excellent thing for online media outlets. It causes outrage and brings a lot of clicks. Tech companies are still seen either as “too clever for normal people” or “probably downright evil and arrogant”. As it is pretty easy to look up online where someone works any ill-advised word from a colleague – or from you for that matter – can and will become quotes like “Company X employee said…” which gives an attack to your company more gravitas. Do not fall into that trap and make sure that you don’t let frustration get the better of you or your colleagues. Keep repeating that you are there for them to talk about frustrating parts of their work.

There are a lot of things you have to be aware of when you are a developer advocate. One of them is the enemy within the company.

Prepare for prejudice

You have a unique role which spans various traditional roles. Especially for developers moving away from the day to day grind can easily be seen as betraying the cause. Prejudiced developers are amazingly proud of being the delivering part of the company and consider anyone who does not code superfluous. I am sure you met these people and heard statements like “I don't know why we need designers, when we use a framework!”. It is somewhat ironic that the people whose standing in the company you try to improve are the ones that are likely to be opposed to your role.

In the end, this is something you will have to live with. You will burn a few bridges and you will have to suffer a lot of internal and external abuse and nagging but it is important to keep your eyes on the goal. If exclusively working as a web developer for 12 years has taught me one thing then it is that delivering awesome work pleases first and foremost yourself. In order to have an impact in the company and to get things changed you have to take your hands off the keyboard and start talking and persuading.

Don't get discouraged by people seemingly stabbing you in the back – in reality this is exactly the miscommunication and lack of people skills that you try to help out with. See it as a challenge and not as a show-stopper. Once you can show successes of improving the standing of developers in the company you can go back and ask what they think of your role now. Most of the time this is not necessary any longer though as the terribly grumpy people either left the company or others start telling them to stop. You can’t please everybody – you are not pizza.

Deal with company changes

As the IT market is constantly changing so do the companies in it. This can be a great thing but in most of the cases it will mean that you have to deal with issues that are beyond of your control. Mergers, acquisitions, new products, products being discontinued, rounds of layoffs, redundancies – all of these things happen, so be prepared.

Fact: The sad fact is that most company changes don’t have anything to do with the quality of your work. The concept of shareholders buying into a company because they believe in it has been dead for years – it is all about trading stocks and moving them to make money in the process. This means that most smaller companies have three months time to turn any new product into a massive success as this is the time in between shareholder meetings. If there is no immediate success then the product gets canned and the people on it with it. This is a terrible state of affairs and it leads to mediocre and short-win driven products instead of great, lasting experiences. And the latter is what good developers are all about.

The thing about you being a developer advocate is that you are in the spotlight of the world and the company so you'll be the first to be asked about an opinion when there is a big change in your company. This can have disastrous effects – either you violate a company policy and tread hard on the toes of your legal, HR, marketing and PR team or you sound like a company drone to the developers in the company. Here are a few things to be aware of:

Tip: This last point is important. As your job is to communicate with everybody in the company people already assume that you know a lot more than they do. As developers get paranoid about changes in the company this can mean that people think you know all about what annoys them but hold back as you are siding with “the company” or “the management”. Don't lose your contact with and the trust of the developers in the company over something you have no control over.

Example: One interesting example of a change was when in one round of redundancies a broadly liked and respected outgoing and extremely talented developer got made redundant. The developer was also part of a team that built one of the most important products at the time. The mailing lists where flaming, people were tweeting about the unfairness of it all and in general everything pointed towards the company having completely lost its marbles. Speaking to HR I got to learn that the reason he was picked was that in a previous round of redundancies he had filed for voluntary redundancy and naturally these were the employees who were picked first. In addition to that talking to the developer himself I found out that he was totally OK with the decision and looked forward to having more time to look after his pet freetime projects and turning them into businesses. All the emails and comments going out failed to either address the developer himself or HR for a statement and this resulted in an avalanche of misinformation and bad blood.

Be there for internal developers

You traveling the world and seemingly spending your work time aimlessly surfing the web and posting on social media can give a wrong impression of you losing interest in being a developer. Work around that by not losing the connection with the people in your company that build things and listen to what they do.

Tip: Don't get bogged down in detailed problems of other developers though. You should be a voice of reason, understanding and pragmatic solutions and you can only be that if you see the work being done from a vantage point.

More importantly, listen hard when developers feel hindered in delivering their job. Then talk to their management about these problems. Keep these talks anonymous and show the impact these problems have on delivery, employee retention and quality of the products your company builds.

Any change for the better you can cause and any work improvement that can be attributed back to you allow you to not be part of the delivery and still keep your tech credibility. You achieve this by talking in the right language at the right time to the right people. Developers are always asked to deliver yesterday what is defined in a week's time and never feel the chance to voice their concerns. Make them aware that you can be their spokesperson and that you are there to demand time for discussing problems with their managers.

Example: I was touched when one of my former colleagues asked me to have a few late night phone calls (over Skype) to talk about his future in the company and an offer he had from another company. I was also very annoyed about how frustrated he was about not feeling any joy or empowerment in his job. The reason was that he didn't dare talking to his manager. My main question in these calls was how he feels about going to the office every day and he said that he dreads it. The decision was clear: if you do not like going to work and you don't feel you have a chance to cause any change – leave. He is now in a new role in a different company, feels excited about the challenges there and left the company not in anger but with a feeling of accomplishment and knowledge that there are caring people in his old company and not only the ones that made him leave.

Work with PR and marketing

As stated in detail beforehand, your role as a developer advocate means that you are in between classic outreach departments like PR and marketing and developers. The danger there is that these departments could see you as competition.

Therefore it is immensely important that you keep on good terms and in constant communication with these departments. The reasons should be obvious:

Only by liaising with the other outreach channels of the company you can make sure that you give the same message. You don't want to be seen as a threat.

Be known as an outward channel

As a lot of people talk about the company to the world on different levels it is a good plan to tell the company about your outward communication channels. This ensures that you are not approaching the same people in parallel and possibly give mixed messages effectively undermining your and your company's credibility. It also shows the company that you are a person that reaches where they can't. List all the places where you publish:

Also make sure to tell people that you have invite codes and accounts for products (if you have them of course). This works a treat and stops people from having to sign up themselves if they just want to have a look.

Train other advocates and developers

Just like forward thinking developers share as much of their knowledge with other developers you should plan for training people in the company to do what you do. The reason is the same in both cases: you can share the workload and you can be sick or take a holiday. Another thing you can do is target new ideas and spend time on other plans what to do with your (professional) life.

There is also the benefit that people that are not like you might have a lot more impact in different channels. If you’re an mid-career developer advocate some of the fast paced new communication channels might feel alien to you and you’d stand out like a sore thumb there. Some of your younger colleagues might actually already use the hot new channel and with a bit of guidance can do much better there than you could ever do.

Training advocates is a tricky thing – by definition advocates should be found and empowered and cannot really be “made”.

Just like you use your powers of communication and persuasion to bring products to developers you can use them to bring potential advocates out of the woodwork:

Tip: A lot of this will tie in nicely with communication channels that PR and marketing already use. Ask them for help instead of doing your own thing and creating confusion and trespass on their territory.

Share useful technology

As a developer advocate, you will have the hand on the pulse of technology. Not everybody has the time to keep up the same way - actually hardly anybody has. That's why an interesting part of your job is to communicate great technology finds with your company.

If you find great tools that make everybody's life easier, share them with the company. This can include things like screenshot tools to stop people from sending you Word documents with embedded resized bitmaps, translation tools, communication tools, automated social media collateral generators – anything that you use to save time every day.

Example: One thing you will find is that if you are an early adopter of technology the main market will get to know some of them a few months later. During my career I had great success helping marketing to set up blogs or newsletters and HR to use Twitter. This creates an amazing amount of goodwill with these departments and it is an easy step for you as you are already excited and knowledgeable about these technologies.

Balance your personal and official channels

One issue you will face sooner or later as a developer advocate is where to put your information. The big mistake there is to use your own, personal channels (blog, Twitter account, YouTube channel, Facebook page and so on) for everything. This is tempting to do, for several reasons:

This is how a lot of personal social media presences work, and well at that. The issue, however, is that once you publish for a certain company you are not just "you" any longer. You are a translator and a voice of a certain company or product and – more importantly – the people working in or on it. That's why it is a bad move to use your own channels as the source for company or product specific information. For various reasons:

All in all, the balance between publishing on your own channels and company official channels is simple: publish detailed information tied to the product where the product is maintained – a company wiki, an official blog maintained by the company, the GitHub repository and similar places. That way you can move on to another company without leaving confusion and a mess behind. It also ensures that web searches in the future find a maintained resource, and that social media updates don't end up in a missing page – the company has a stake in keeping an official resource available. As an advocate, your job is to raise the profile of the company creating the product you promote and the product itself. Thus the official pages with the up-to-date information should show up higher in search results than your own blog. Otherwise you failed at doing your job. You are a pointer, a transmitter – not a replacement.

What you publish on your own channels should whet the appetite of your readers to go to the official place and learn more. This could include translations, a quick screencast, screenshots, a nice demo using the technology (instead of being it). Think of your company's product as a movie and you are the one who cuts and releases the trailers in various places to get people excited about it.

There is a fine line between promoting your company's work and taking credit for it. Don't cross it and you'll help the company and keep being a trustworthy resource and communication channel.

Remove the brand

One crucial part to becoming a successful developer advocate is to remove the brand from your thinking.

Yes, you work for a certain company that builds a lot of products, some of them cool – some of them terrible. The point of developer advocacy is not to get people excited about the brand or the company behind it though. It is about the products the company releases and even more specifically about getting developers excited about playing with them. Your goal as a developer advocate is to get developers to talk about your products and promote them for you. This is why you need to try your best to remove yourself from the brand of your company to set an example. This is tough. The larger and more known the company you work for is, the more people will try to paint you as “the company X person”. We’ll deal with this later in the book, but it is something to prepare yourself for.

Separating yourself from the brand and towards the product only works when you are excited about the product. If the department that builds the product fails to get you interested in the product, don't talk about it – instead, work with the department to find the thing that makes it worth while for you. Anything you advocate should answer one simple question: What is in it for developers?

The products you advocate need to get you excited and you need to know where they are going and who to ask for detailed information about them. If the product has no internal stakeholder or team that is a danger sign.

People working on products are actually not the right people to advocate them – they are far too close to the subject matter to find obvious flaws in the documentation. They are also fine with overly complex functionality as they are used to it. This goes as far as having their own language. Every product I worked with used specialist terms that in day-to-day conversation made sense to the team but would be cryptic gibberish to put in a blog post.

Your job is to offer them a way to translate this into easier understandable documentation and examples and challenge their current state of affairs. You do however need them to do a good job so be careful not to burn any bridges by being too critical. People spent a lot of time building what you want to tell the world about and are protective about it.

The real power of removing your brand goggles is that you will be able to work with rather than against the competition.

Next: Working with your competition