Articles

Seven years ago I had the chance to visit China, and I had a great time exploring the cultural heritage, large cities and gastronomy. So when my talk got accepted for the first DevRelCon in Asia, I was excited to see China again — this time from a professional point of view.

On the Write The Docs London meetup in January speakers from leading Git code repositories talked about how their teams dogfood their own tools to do their documentation. Version the Docs covered Bitbucket and GitLab, but we missed a GitHub presentation. To fill this gap, we interviewed Anne Gentle about GitHub, treating docs like code, and community contributions to documentation.

The annual North-American Write The Docs conference this year featured 2 API documentation redo presentations:

1. Lyzi Diamond described Mapbox (formerly a part of Development Seed) documentation automagic in detail,
2. Sarah Hersh talked about the journey that NPR One undertook towards a new task-based approach for their API's developer documentation.

In this post we aim to give you an account of these presentations.

Most of the time when we talk about developer experience, we mean downstream DX, the experience of developers that implement APIs. But what about the developers that create APIs? In a previous post we wrote about the 8 stakeholders of developer portals, we argued that while the developers that use APIs are important, we shouldn’t forget about the experience of other stakeholders of a developer portal. In this post I’ll explore the experience of one of these audiences - the API developers - and explain what upstream DX is, when it matters, and how you can use a developer portal to improve it.

As part of our work to make Drupal 8 the leading CMS for developer portals, we are implementing a mechanism to import the OpenAPI (formerly known as Swagger) specification format. This is a crucial feature not only for dedicated developer portals, but also for all Drupal sites that are exposing an API. Now that it has become much easier to create a RESTful API service in Drupal 8, the next step is to make it more straightforward to create its API reference documentation. That is why we think our work will be useful for site builders, and not just for technical writers and API product owners.

Different stakeholders interact with a developer portal throughout an API’s lifecycle. In this post I’ll list 8 stakeholders and explain what they need to do their jobs.

We explored free and open source API documentation solutions, and compiled the results of our research in this post.

Web APIs are not just useful when making headless sites in Drupal: large Drupal sites often hold valuable information that could also be useful outside the site's context. Media companies might want to expose historical media content, community sites could show data about their community activities, e-commerce sites tend to open an API for their affiliates and partners.

While it is possible to use Drupal 7 and Drupal 8 as an API backend, a lot of functionalities that describe a mature API service do not come out of the box. In this post we will explain what key concepts you have to keep in mind when designing an API service, why they are important and how APIgee Edge can make it easier to build a full-featured API webservice in Drupal successfully.

Where does technical documentation stand with agile development methods? Watch and read about the talk Rob Woodgate (@agiledoc) did at the Write the Docs London-GDS mini conference on the practice of agile documentation.

In a talk we did at FOSDEM ‘17, Tamás Demeter-Haludka and I discuss potential application areas of graph databases in existing open source CMSs like Drupal.

Developer portals are important for your API's adoption and support. They are also a trust signal: a well designed and actively maintained developer portal shows that an organization is investing in its APIs. It helps convince developers that they can rely on them. In this post I’ll zoom in on the trust signals business model, partner policy, API quality, API uptime status, versioning policy, documentation and developer portal production quality.

At the API days in London, I gave a presentation about developer portals. In it I shared mental models and frameworks that I think can help improve the quality of a developer portal: I decided to write 6 dedicated blog posts about what I discussed.