The Seven Artifacts of Developer Advocacy Projects

Over the past 16 years, mostly as a Developer Advocate, I’ve developed a framework to help developers learn and get excited about something new.  I believe generating excitement is the primary goal of advocacy. 

Each developer advocacy project ideally produces seven artifacts:

  1. Code Samples
  2. A Blog Post
  3. A Presentation and/or Video
  4. A Hands-On Workshop
  5. Broad Social Media Reach
  6. Product Feedback
  7. Enriched Community, Partner, or Customer Relationships

I’ve found that doing all seven produces the greatest impact. The amount of effort decreases with each subsequent item while the effect grows.

The seven artifacts share a common goal for each project.  Start with a goal framed around the audience and their take-away.  For example, a recent project taught Java developers different methods of creating Docker containers so they make better decisions when choosing containerization technologies.  All artifacts supported that goal.

Let’s explore each artifact type.

Code Samples

A primary way that developers learn is through simple, relevant, working examples.   “Simple” means something different to everyone so I think about it in terms of “The simplest thing that could possibly work” (a phrase my friend Bruce Eckel has told me many times).  Samples are abstractions; they hide and reveal aspects.  What you hide and reveal must be consistent with the goal of the sample and the target audience.

I built a sample to teach developers to containerize Java applications.  The code was as simple as possible, utilizing an HTTP Server API that no one would really use in reality.  That was OK because the code was irrelevant to the goal.

When parts of a sample are relevant to the goal, they should be real-world applicable.  A “never do this in production” disclaimer on goal-relevant parts of a sample suggests you should re-work the sample.

It is shocking how often code samples do not work.  Make sure you put your QA hat on and thoroughly test your samples.  When recording screencasts for my samples I’ve often discovered issues with them.  Testing your samples on other machines can reveal implicit environmental assumptions you’ve made.

A Blog Post

A well-written and informative blog post is one of the most valuable things you can create. As someone who loves to write code, writing prose is challenging.  It takes a unique focus.   Revisit your goal often and if something doesn’t fit the goal, move it to your blog backlog.

Another lesson Bruce Eckel has imprinted in my brain is to “start with why.”  Describe the problem you are solving and the motivating reason for the project.  Then go into the details.  My blogs are often oriented around getting developers’ hands onto something so sometimes they can be the “Hands-On Workshop” artifact of a project.  Sometimes the “Presentation / Video” artifacts are included.  For each blog post, the “Code Sample” artifact is referenced and explained.

For example, see: Buildpacks vs Jib vs Dockerfile: Comparing containerization methods

A Presentation and/or Video

There are different styles for presentations and demos.  Sometimes my projects are driven by conference presentations.  When they are not, I usually record a video walkthrough / demo of the project.   It’s important to be your honest self and avoid smoke & mirrors.  If you record your voice (which I highly recommend), use the best headset or microphone you can find.  Bad audio is annoying and distracting for the viewer.  In this video where I compared docker container methods, the conference didn’t want me to wear a headset.  The audio would have been much cleaner with a good headset.

For screencast demos, I often do 5 - 10 “takes” because I make mistakes.  This can be frustrating for a long recording, but it produces better, clearer, and more concise results.

A Hands-On Workshop

Developers learn from examples but learn even more from getting their hands on something.  I try to create live hands-on workshops for each project.  These lead the attendees through the content and help them if they get stuck.  The workshop content is usually published for self-guided use.

Creating a workshop usually reveals areas of product friction which should be tracked for the “Product Feedback” artifact.  I often spend huge amounts of time making steps that are the simplest thing that could possibly work.  It is also critical to completely test the workshop from end-to-end to ensure a good user experience.  This can feel tedious and boring after writing the content, but each time I discover something that needs to be fixed.

I recently co-created a workshop called “Hands-On Google Cloud & Confluent Cloud: Real-time Data and Warehousing” and thanks to rigorous testing, every attendee was able to get through the 3 hour workshop (where about a dozen different technologies were used), without any issues.

Broad Social Media Reach

Posting about your projects on Twitter, LinkedIn, etc is par for the course but you can gain extra amplification by asking others to help.  If your organization has an official Developer Marketing team, ask them to share your projects.  It can be helpful to get them involved early in the process.  Friends and co-workers can also help you promote your projects.  It takes energy to go beyond just a single tweet but if you want to reach a broader audience, it is time well spent.

At Google, I’m lucky to have the support of a Twitter channel with over 2m followers. Their tweet about one of my blogs helped the post receive tens of thousands of reads.

Product Feedback

Every Developer Advocate project should improve its related products.  Sometimes this comes in the form of bug reports.  Another tool is a “Friction Log” in a “captain’s log” form to capture the experience of a developer trying to accomplish a given goal.  For example, see my (now out-of-date) Friction Log for getting started with the Unison programming language.  Sometimes I capture these experiences as screencasts, but ultimately the goal is to help product teams see what it is like for one of their target users to accomplish a real-life task.

Other ways to provide product feedback include proposals and conversations with product managers.  Ultimately one of the best things Developer Advocates bring to an organization is a bridge between the internal product people and the developers they want to reach.  Developer Advocates should help mold the product into something that developers get excited about and use.

Enriched Community, Partner, or Customer Relationships

The best advocacy is not from me, but from community members, partners, and customers.  One of the most important things I do is build relationships and nurture others into being advocates.  Projects are a great catalyst for these relationships and the interaction model can vary to fit the circumstances.  Most other artifacts can be co-developed / co-delivered with others.  Whether it is co-presenting at a conference or co-creating a code example, these interactions provide great opportunities for building relationships.

For example, I’ve developed a close relationship with Bruce Eckel and learned much from him over the past ~15 years.  We’ve worked on many projects together and now have a podcast and regularly present at conferences (most recently at SpringOne).  I’m incredibly grateful for this mentoring & friendship, but Bruce has also helped me reach an audience which I wouldn’t have been able to do alone.  There have been many other people I’ve built amazing relationships with over the years. This has been the most fulfilling & impactful part of the job.

All Seven Artifacts

If you are a Developer Advocate, creating all seven of these artifacts for each project helps developers learn and get excited about your technologies.  Give it a try and let me know how it goes!

Thanks to Bruce Eckel for helping me with this blog.