Edit: API Tool Tutorial

As the managing editor of a popular developer content hub, I chose the topics that resonated well with our audience. In 2017, APIs and any tools to model, develop, test, and manage them were hot topics. One team in the UK who developed a popular API tool kept me busy. They often needed me for editing a tutorial about some new and innovative way our developer audience could use their tool. I was happy to oblige because their content was quite popular in our hub.

One voice for multiple authors

The tutorial was written by three authors. Editing a tutorial with this many authors wasn’t unusual for me. I became adept at it from my IBM Redbooks days. In this particular draft, as I read through it, I could sense their individual voices and observed their unique writing styles. This would never fly with our global audience.

Having spent years serving on our corporate style council and being well familiar with the Chicago Manual of Style, I was well-poised to turn their three voices into one. Having this style knowledge makes editing a tutorial with multiple authors much easier than it sounds.

I started with a developmental edit, where I looked for clarity issues, missing information, and overall organization. After the team provided their feedback on my initial questions, I edited the tutorial for style, grammar, and spelling. Our corporate style helped guide the voice of the company and the authors that I needed to convey in the final version.

Not your typical tutorial edit

When the team submitted their project for editing, they mentioned that they also had a demo video. I asked for the link to the video so I could watch it. It was short, maybe only a few minutes long at most. And, it was to the point in that it focused on the steps from the tutorial. What better way to learn a new skill for our audience than to combine the tutorial and the video!

So, I worked with the team to get the source of the video so I could upload it to our channel on YouTube. Before I uploaded it, I created a title and back slide that I added to the video in Apple iMovie. The back slide provided information about our hub to encourage viewers to go there for more information about the topic. In the YouTube description, I included a direct link to the tutorial in the content hub.

Further audience reach for greater hub traffic

Combining the two content types offered several benefits. First, it provided documented steps for our developer audience who needed to try to reproduce them right in their environment. Second, it allowed visual learners to see the code in action. Third, both the tutorial and the video on YouTube linked to each other. So, as an added bonus, it drove more traffic to our content hub even if the audience found the video on YouTube. In other words, if they wanted to follow the steps after seeing the video, they could link to the tutorial on our site.

The following PDF shows the final tutorial with a marker for the video.

Editor’s note: This tutorial has since been archived and so has the video.