Skip to main content
Information Architect
Sep 27, 2017

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:

  • Educate users:

    • Demos and mashups help users explore the API and its functionalities.

    • Blog posts often contain code samples and help with problems in specific areas.

  • Build trust:

    • 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 :

1. Discover

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.

alt
Use cases or case studies (Dwolla blog)

 

Developer Stories (Slack Blog)
Developer Stories (Slack Blog)

 

2. Evaluate

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.

Test Keen IO (Keen IO blog)
Test Keen IO (Keen IO blog)

  

Examples of an integration: complete use case/tutorial with code snippets, written in plain English (Twilio blog)
Examples of an integration: complete use case/tutorial with code snippets, written in plain English (Twilio blog)

 

Example of a sample app article (Dropbox developer blog)
CenturyLink provides a blog topic “tutorial”, but this page is also directly available from the top menu (CenturyLink blog)

 

Example of a sample app article (Dropbox developer blog)
Example of a sample app article (Dropbox developer blog)

 

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.

Topic selector (IBM developerWorks blog)
Topic selector (IBM developerWorks blog)

 

Guest article on customizations, explaining several concepts (by Pronovix, Apigee blog)
Guest article on customizations, explaining several concepts (by Pronovix, Apigee blog)

4. Troubleshoot

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.

Example of an article with code snippets (Twilio blog)
Example of an article with code snippets (Twilio blog)

 

5. Celebrate

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.

Community section (Twitter blog)
Community section (Twitter blog)

 

Interview section (CenturyLink blog)
Interview section (CenturyLink blog)

 

Event news (Mapbox blog)
Event news (Mapbox blog)

 

6. Maintain

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.

Post with explanations how to generate release notes (Apigee blog)
Post with explanations how to generate release notes (Apigee blog)

 

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.

DigitalOcean’s blog with audience focused topics
DigitalOcean’s blog with audience focused 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:
  • Either with an overview page of blog posts on the company site, while the separate articles are published on Medium (Keen IO),
  • Or also sometimes with the whole blog on Medium (Slack).

“Developer News” (Facebook blog)
“Developer News” (Facebook blog)

 

Blog on Medium (Slack blog)
Blog on Medium (Slack blog)

 

Subcomponents:

  • 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.

Audience focused blogs (Dropbox blogs)
Audience focused blogs (Dropbox blogs)

 

List of contributors (StackOverflow blog)
List of contributors (StackOverflow blog)

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.

Google has too many labels to choose from: +50 for the letter “A” alone (Google blog)
Google has too many labels to choose from: +50 for the letter “A” alone (Google blog)

 

  • 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.

Developer portal footer: hits from the blog (Twilio)
Developer portal footer: hits from the blog (Twilio)

 

  • Indicate how much time the reader will have to spend on your article.

Indication of reading time (Keen IO blog)
Indication of reading time (Keen IO blog)

 

 

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!

Kathleen is an information architect helping clients find out how to align business goals and user needs with the knowledge we gathered about devportals. She grew her expertise through early research on developer portals to determine components, strategy, and best practices for user experience. She holds master's degrees in history and in archival science & records management.

Newsletter

Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.

 

Subscribe