michaelheap.com

The TAPE Model for Content

2023-03-20T11:00:17Z

Content is a mainstay of many Developer Relations teams, but it can sometimes be tough to show the impact that you’re having. Content on your company blog can be instrumented and attributed well, but what about things like YouTube videos or recorded conference talks?

You can build out complex tracking systems with UTM parameters and short URLs, but there’s an easier way to understand how your content is being used. It all starts with your internal teams.

DevRel is typically a cost centre. There isn’t any revenue attributed directly to the team. The best way I’ve found to justify your existence (and yes, unfortunately this is a thing in every business) is to attach yourself to the revenue generating teams.

Serving your internal audience has two outcomes:

You support teams that drive new business. The sales team can link to your videos to show prospective customers the capabilities of your platform and how easy it is to use
You save time for existing teams, which means you’re saving $$$. Every proof of concept cycle that is 10% faster thanks to your demo videos is money that the business isn’t spending on Sales Engineers. Every support ticket that is replied to with a link to your content is time that an agent doesn’t have to spend writing a response.

In both of these cases you’re drawing a direct link between the content that you’re producing and the impact it has on the revenue or efficiency of the business.

This is where the TAPE model comes in.

TAPE stands for Trigger, Action, People, Examples.

Trigger: Why are we producing this content? What problems have we observed that we can help solve?
Action: What are we producing? Is this best presented in the documentation, as a blog post, as a video etc?
People: Who is asking for this? Not our end customers, but our internal stakeholders. Can we make other teams successful?
Examples: Where is this being used? Is your content being used to solve support tickets? Is it being used to prove we have certain capabilities during an RFP?

By matching the content you produce to pain points that internal teams are having you know that the content is going to resonate with at least one audience. This is your trigger, your reason for producing the content in the first place.

Understanding who’s going to consume your content helps you decide which action to take. A VP of infrastructure is more likely to scan a documentation page than watch a video. A developer at a Global System Integrator might be more at home with a 60 minute deep dive video on to how to write plugins for your system.

Aim to make friends by supporting the right people. If you’re working with the sales team, target enterprise sales reps rather than lower value digital customers. If you’re working with Sales Engineers, work with regional leads who can help evangelise the work you do more widely. Saying “I helped $VP with $TOP10 customer” is much more impactful than saying “I solved 10 loosely related support tickets”

Then finally, keep track of how your content is being used. Make a note every time someone links to one of your pieces of content in Slack. This could be a product manager asking how a feature built before they joined works. It could be someone from marketing asking how a new feature behaves so that they can position it correctly. Building up a list of examples allows you to show that not only did you identify an opportunity to support people internally, the content is being used repeatedly to help enable the rest of the business.

Examples

Alright, so what does that actually look like? Here are five examples to get you started.

Trigger: Product decision to deprecate a feature
Action: FAQ, migration recommendations
People: CPO, Support, Docs Team, Customer Success
Examples: CPO shares with internal teams. Support use with inbound tickets. Docs team write public facing docs. Customer Success proactively reach out to their customers to explain how to migrate.

Trigger: New feature released
Action: 3 minute demo video showing how it works
People: Product Manager, Product Marketing, Social Media Manager, Solutions Engineers, Sales
Examples: Product Manager / Product Marketing used in sales enablement. Social media used for a blog post. Solutions engineers used as a basis for their own demos. Sales used to show prospects the platform capabilities.

Trigger: Marketing campaign by competitor
Action: Rebuttal video showing off product capabilities
People: Product Marketing, Sales
Examples: Product Marketing builds battle cards using the information. Sales use the content to influence champions within a business.

Trigger: Difficult to run your OSS project on MacOS
Action: Work on README and improving error messages in the app
People: Engineering, Community, Support
Examples: Increased contribution velocity for engineering. A community develops around your project. Reduced support ticket volume for common use cases

Trigger: An event is looking for a speaker
Action: Write and present a talk
People: Marketing, Sales
Examples: Marketing run the event with good attendance to drive MQLs. Sales use the content to show off platform capabilities with potential customers.

Conclusion

Using internal triggers as your source of content ideas allows you to map your contributions to the goals of other teams. Many of these teams contribute directly to revenue, and if you make them successful it’s easy to show the impact you’re having on the business.

It might be tempting at this point to try to add some attribution directly to your team. You might negotiate that 2% of every sale where your material is used is attributed to your team.

This is a trap.

If you can claim 2% of every deal (and this is a high percentage), you need to do 100 deals worth $500,000 every single year to get $1 million in attribution. If you’re impacting 100 deals per year, chances are that you’ve got a large-ish team who are definitely costing more than $1 million per year.

Instead, focus on the relationships. People trust people. A VP saying “that DevRel team sure are awesome. They’ve cut our sales cycle by 2 weeks” is worth much more than 2% of a sale.

Filter Google Analytics report

2022-11-29T13:58:08Z

I'm trying out Radar to keep track of analytics at a glance. It's Google Analytics collection works great, but the way that we've set up Google Analytics the data for multiple sites ends up in the same property.

I wanted to filter the report to only traffic to a specific subdomain. It took me too long to work out that I needed a dimensionFilterClauses entry with the ga:pagePath (via the schema).

Here's how to filter your reports in case you (or I) need to do it in the future:

json
{
  "reportRequests": [
    {
      "viewId": "YOUR_VIEW_ID",
      "dateRanges": [
        {
          "startDate": "today",
          "endDate": "today"
        }
      ],
      "dimensions": [
        {
          "name": "ga:date"
        }
      ],
      "metrics": [
        {
          "expression": "ga:pageviews"
        }
      ],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:pagePath",
              "operator": "PARTIAL",
              "expressions": ["docs.konghq.com"]
            }
          ]
        }
      ]
    }
  ]
}

Other things that may be useful:

Endpoint: https://analyticsreporting.googleapis.com/v4/reports:batchGet
Method: POST
Auth: Bearer [token]

Then transform the results using the following JS snippet:

javascript
const pageCount = Number(
  data.reports[0].data.totals[0].values[0]
).toLocaleString();

Upgrade from Winston 2 to 3 using colors

2022-10-23T11:39:59Z

I updated a project from Winston 2 to Winston 3 this morning and needed to make a few changes to how it was configured.

I previously created a logger instance, then switched to using syslog levels with a custom colour scheme. Here's how I did it in Winston 2:

javascript
var winston = require("winston");
var logger = new winston.Logger({
  transports: [
    new winston.transports.Console({
      level: "warning",
      colorize: true,
    }),
  ],
});
syslogColors = {
  debug: "rainbow",
  info: "cyan",
  notice: "white",
  warning: "yellow",
  error: "bold red",
  crit: "inverse yellow",
  alert: "bold inverse red",
  emerg: "bold inverse magenta",
};
winston.addColors(syslogColors);
logger.setLevels(winston.config.syslog.levels);

In Winston 3, the new winston.Logger call has been replaced with winston.createLogger, levels must be provided in the constructor, and formatting is handled by individual formatters using the logform library.

Here's how to achieve the same thing as above in Winston 3:

javascript
const winston = require("winston");
const syslogColors = {
  debug: "rainbow",
  info: "cyan",
  notice: "white",
  warning: "yellow",
  error: "bold red",
  crit: "inverse yellow",
  alert: "bold inverse red",
  emerg: "bold inverse magenta",
};
let format = winston.format.combine(
  winston.format.colorize({
    all: true,
    colors: syslogColors,
  }),
  winston.format.simple()
);
var logger = winston.createLogger({
  transports: [
    new winston.transports.Console({
      level: "warning",
      format,
    }),
  ],
  levels: winston.config.syslog.levels,
});

Running `gickup` on a QNAP NAS

2022-10-15T18:00:01Z

I learned about Gickup whilst reading Jeff Geerling’s backup plan and thought it would be a useful thing to run for my own repos.

I initially ran it on my local machine periodically, then realised that I could run it on my QNAP NAS every night. Here’s how I did it:

Create a shared folder named gickup to contain the backups. I’ve got a volume named Backups that contains this, but any volume will do
Create a directory to store your backups by running mkdir -p /share/gickup/repos
Edit /etc/config/crontab and add the following line to the end: 0 3 * * * docker run --rm -v /share/gickup:/hostvol buddyspencer/gickup:0.9 /gickup/app /hostvol/config.yml > /share/gickup/last-run.log 2>&1. This will run gickup every day at 3am
Reload cron to pick up that change by running crontab /etc/config/crontab && /etc/init.d/crond.sh restart

You may have noticed that I reference /hostvol/config.yml. I mount the /share/gickup folder a /hostvol, and config.yml is my gickup configuration file. Here’s what it looks like:

yaml
# config.yml in /share/gickup
source:
  github:
    - token: CHANGE_ME_TO_YOUR_GITHUB_PAT
      excludeorgs: # this excludes repos from the organizations "foo" and "bar"
        - foo
        - bar
destination:
  local:
    - path: /hostvol/repos
      structured: true

Create your own config.yml, making sure you change the token value. If you’ve configured all of the above, all the repositories you have access to will be backed up at 3am each day.

Transcribe audio locally on MacOS

2022-10-14T12:01:20Z

I've been using Just Press Record on my watch to capture things that are on my mind whilst working outdoors. I'm usually pretty good at processing the recordings regularly, but recently found a folder of recordings that I may or may not have processed.

Rather than listening to all of the recordings, I wanted to batch transcribe them and read the text. There are plenty of online tools available, but I wanted a local CLI tool which lead me to hear.

The 0.1 release of hear is from March and is missing some important bugfixes. I cloned the repo and ran make to build the tool locally and it works great.

hear accepts an input file and a language, and writes the output to stdout. Here's an example that processes a file against the en-GB model and writes out transcription.txt:

bash
hear -i ./2022-01-29/10-17-46.m4a -l en-GB > transcription.txt

Important: You may see the word abort when running hear. This is due to hear needing to request microphone permissions. If you get an error, try running hear in Terminal.app rather than any other application

If you have a whole folder of recordings to transcribe, you might find this snippet useful. It produces a .txt file next to each recording with the contents of the transcription:

bash
for i in `find . -name '*.m4a'`; do hear -i $i -l en-GB > ${i/.m4a/}.txt; done

Here's what it looks like for me after running that command (with some folders removed for brevity):

❯ ls -R
2021-12-27	2022-01-29

./2021-12-27:
14-17-39.m4a	14-19-34.m4a	14-21-18.m4a	14-21-54.m4a	14-49-09.m4a	14-53-17.m4a
14-17-39.txt	14-19-34.txt	14-21-18.txt	14-21-54.txt	14-49-09.txt	14-53-17.txt

./2022-01-29:
10-17-46.m4a	10-17-46.txt	10-56-59.m4a	10-56-59.txt

Secrets Management in Kong is Now GA!

2022-10-10T00:00:01Z

See https://konghq.com/blog/secrets-management

Mock `process.env` using `mocked-env`

2022-10-07T10:18:07Z

When testing values in process.env, they persist for all further tests in your test suite. This can have unwanted side effects, making tests pass or fail unintentionally.

Using mocked-env, you can reset the environment to the pre-test state after every test runs. It works by taking a copy of process.env when you call mockEnv, then restores it once the test has run (afterEach).

Here's an example that shows how environment variables set earlier in the test suite don't persist in to later tests:

javascript
const mockEnv = require("mocked-env");
// Variables to store references to what we need to reset
let restore;
let restoreTest;
beforeEach(() => {
  restore = mockEnv({
    VALUE_ONE: "Hello",
  });
  restoreTest = () => {};
});
afterEach(() => {
  restore();
  restoreTest();
});
test("environment concatenation (world)", async () => {
  restoreTest = mockEnv({
    VALUE_TWO: "World",
  });
  expect(concatenateValuesFromEnv("VALUE_ONE", "VALUE_TWO")).toBe(
    "Hello World"
  );
});
test("environment concatenation (michael)", async () => {
  restoreTest = mockEnv({
    VALUE_TWO: "Michael",
  });
  expect(concatenateValuesFromEnv("VALUE_ONE", "VALUE_TWO")).toBe(
    "Hello Michael"
  );
});
test("environment concatenation (missing value)", async () => {
  expect(concatenateValuesFromEnv("VALUE_ONE", "VALUE_TWO")).toBe("Hello ");
});
function concantenateValuesFromEnv(a, b) {
  return `${process.env[a]} ${process.env[b]}`;
}

Without using mocked-env, the last test would fail as the returned value would be Hello Michael as VALUE_TWO is set in the previous test, and would not be cleaned up without mocked-env.

Using `GITHUB_TOKEN` as a default `input` value

2022-10-07T10:10:27Z

If you need to authenticate against the GitHub API in your GitHub Action, you might prompt the user to provide their GITHUB_TOKEN secret through an input. This isn't necessarily needed thanks to the github.token context and default input values.

You can gain access to the GITHUB_TOKEN secret by default by configuring your action.yml file to access github.token:

yaml
name: Action Name
description: My awesome description goes here
runs:
  using: node12
  main: dist/index.js
inputs:
  token:
    description: The GitHub token to use when calling the API
    default: ${{ github.token }}
    required: false

Announcing General Availability of Kong Gateway 3.0

2022-09-28T00:00:01Z

See https://konghq.com/blog/kong-gateway-3-0

API Composition with StepZen and Kong

2022-09-15T00:00:01Z

See https://konghq.com/blog/api-composition-with-stepzen-and-kong