Companies use blogs as an informal, unstructured communication tool that can engage current and future customers and members of their wider community. Blogs are often used to start and maintain relationships, to update an audience, discuss new functionalities, and to inform about company decisions. Because blog posts are published as a sequential series of updates, they create a fleeting feeling of urgency, serendipity and newsworthiness, which makes it much more likely visitors will share blog posts through social networks.
Blogs also function as a content incubator: an unstructured area in the content architecture where you can develop new types of content for your developer portal, a place where new content types “incubate” before they get their own place, like a company's first "getting started tutorial" or "how to do XYZ" guides.
Most API teams use blog posts on their developer portal or business site as a collection of documentation formats (tutorials, testimonials, interviews, guides etc). Blog posts can:
- Demos and mashups help users explore the API and its functionalities.
- Blog posts often contain code samples and help with problems in specific areas.
- The frequency of blog posts, and the time since the last update are an indicator of the health of an API.
- Blog posts can communicate policies and team culture.
Blogs can help fulfill these needs throughout the whole API implementation process. In this post I’ll explore how blogs can serve the portal users’ needs throughout the different stages of the developer journey. I’ll discuss their labels and subcomponents, and extract best practices. To finalize, I’ll list some questions to keep in mind when deciding whether, when and how to plan a blog on your developer portal.
To write this post, I reviewed the blogs of Adyen, Amazon, Apigee, CenturyLink, DigitalOcean, Dropbox, Dwolla, Facebook, GitHub, Google, IBM, Instagram, Keen IO, LinkedIn, Mapbox, Orange, Pinterest, Slack, Spotify, StackOverflow, Stripe, Twilio and Twitter. These companies have active communities and/or provide a wide variety of developer resources. I explored how they organize their blogs and what purposes the blogs serve.
Blogs in the developer journey
The blogs in our research sample announced events, hooked their users, explained functionalities, communicated company decisions, linked to other documentation resources, provided support in certain areas, explained concepts (domain language), provided code samples, and encouraged users to think out of the box when applying the API. Blogs are generally filled with videos, images, screenshots and explanations in everyday English.
Developers go through 6 stages when implementing an API into an application. These 6 stages are discover, evaluate, get started, troubleshoot, celebrate, and maintain :
Optimize the API for search engines: blog posts are often keyword sensitive, they might help users to find their way to the developer portal and its documentation.
Role: The blog as a marketing tool in the developer’s exploration phase
- Hook users, get them interested in the API product (e.g. add code samples for developers).
- Add user stories and case studies to reach out to other decision makers, like product owners and marketing engineers).
- Show interesting integrations that require out of the box thinking.
Enable people to evaluate what’s on site, via mock APIs, test accounts, tutorials, sample apps: blog posts and articles can explain how an API works, and how it can be implemented in plain English.
Role: Blog posts as a collection of (best) practices
- Show expertise: blog post writers bundle knowledge about a specific topic.
- Highlight interesting or popular integration examples and tutorials.
3. Get started
Blog posts can include code samples, test cases and user stories that might inspire fellow developers to get started with their implementation.
Role: Blog posts as onboarding tools
- Include articles for both beginner and experienced users.
- Provide information about your products, e.g. via a topic selector.
- Link to the portal’s knowledge base to find more information on certain topics.
- Explain concepts that your users might need to know before implementing.
Blog posts explain and communicate about problem areas and function therefore as support tools. Blog posts are also an internal evaluation tool: e.g. to explain a product works you will also be to testing it at the same time.
Role: Blog posts as support resources
- Explain problem areas in plain English.
- Include code snippets.
Show developers that you care about their work: offer them a place on your portal, e.g. via guest posts or in interviews.
Role: Blogs can help grow a community
- Add Call-to-Actions to trigger readers.
- Write series on certain topics, in order to make users return to an interesting story.
- Include real life examples (via interviews, podcasts, guest posts, user stories).
- Announce events, write recaps.
- Provide articles that deal with everyday life tips (e.g. Keen IO’s Culture blog section).
- Make community sections.
- “Put a URL on it”: turn questions from the community into URLs, and provide blog posts to make it easier for users to find the content they are looking for.
Companies can use their blog to communicate about the API health.
Role: Blog posts indicate API availability and reliability
- Dedicate articles to news related to API uptime and release notes.
- Illustrate your services that help developers maintain their API integration with examples, use cases or guidelines.
Labels and subcomponents
In our research sample, we found developer portal blogs (blogs that are directly accessible from the developer portal) and more general blogs that also listed developer topics.
We found several labels:
- Companies put links to blogs in headers, footers, top menu bars, and sidebars reachable under category labels like blog, news, company, community, support, learn more, menu and products, API and docs.
- Blogs often received personalized names: besides “blog” or “developer blog”, we found Developer News (Facebook), The Event Log (Keen IO), Spotify Labs (Spotify), Updates (Dwolla), Changes (GitHub).
- Apart from their “What’s new” page, Orange has a monthly newsletter, where they discuss topics that concern several aspects of the company.
- Medium as a platform for a company blog:
- Design elements, like gifs and images to hook users
- Categories, labels, topics, tags to make article selection easier
- Audience focused topics, categories or blogs to address different users
- Subscribe CTAs on the overview page and on blog post pages
- Links to social media, potentially with the total number of shares (twitter, facebook, linkedIn, google) for social proof
- List of contributors or authors to check writer IDs.
Best practices and remarks
Along my research, I found a few tips and tricks that could help to attract and inspire users:
- Make the search function user-friendly:
- Opt for topics and categories on top of the page (and not only at the bottom of the article).
- Turn questions from your users into URLs via blog posts.
- Choose maximum 15 topics or labels to define article categories.
- Archive older posts, but make sure readers can still find them via tags or labels that indicate the article categories. No-one likes to struggle through - only - chronologically ordered articles.
- Provide CTAs at the end of each post to make sure your users can easily subscribe.
- Remove outdated blogs.
- List contributors and plan what you will include in the author biographies.
- Focus on different audiences through topics or via separate blogs.
- Provide links to other documentation types (like API references, support pages) on your blog to facilitate onboarding and to make it easier to replicate a demo. And vice-versa: give developer portal visitors the opportunity to check blog articles easily.
- Indicate how much time the reader will have to spend on your article.
Considering a blog as part of your communication strategy? Questions to answer
A blog is a great tool to help you develop new types of content on your developer portal. If you want to iteratively develop your content, and build out your content architecture as your community grows, it is a great place to experiment with delivery formats and documentation types. But before you start you need to ask if your company is ready to maintain one?
- Have you got a writer (team) or guest bloggers, a designer, a content strategist at your disposal?
- How regularly can you produce new content?
- Do you want to host your blog on your developer portal (and keep users on your site to find answers) or go for alternative platforms, like Medium, with custom design options, where you get an inbuilt audience and some distance from your brand to allow for experimentation?
We are working on a series of content services for developer portals, want to start a blog but need some help? - Get in touch!