How to plan a developer portal and learning site around user goals

A developer portal and a learning site do different jobs.

Documentation helps someone complete a task or find a precise answer. A learning site takes them from their current level of knowledge to a defined capability.

Many organisations put both types of content into the same website without planning how they fit together. The result is a large library with good search, plenty of pages, but no obvious place to begin.

Cherryleaf has helped a number of clients create developer portals, but in nearly all cases, the learning content has been treated as a separate project, run by a different, internal, team.

Vonage has taken an optimised approach with its new “Developer Portal Learning Center”. The implementation is specific to its APIs, but the underlying strategy applies to any organisation planning a combined documentation and learning service. Last week, they launched the latest beta of their site and described how they got there at the Write the Docs London Meetup.

The main lesson is simple: plan the route through the information before choosing the technology.

Start with the problem, not the platform

Like many large organisations, Vonage already had extensive API documentation. The problem was users could struggle to work out where to start, what to read next and which documents belonged together.

This is a common documentation problem.

It’s important to recognise you can have different types of users reading the content. They can have different goals. For example:

• A reference page can explain every API parameter accurately and still leave a new developer unsure how to build a working application.
• A collection of how-to guides can answer individual questions without explaining the larger process to a product manager deciding whether to invest time and money in using your API.

Adding a new CMS will not fix that.

Before discussing templates or software, it’s important to define the outcomes the site should support. For example:

• Help a new user make their first successful API call.
• Explain a proposed solution to a business decision-maker.
• Teach a developer how several products work together.
• Support a customer moving from a competing product.
• Reduce the number of support requests about a known process.
• Give experienced users direct access to reference information.

These outcomes are more useful than a requirement such as “create a learning portal”. They tell the team what users should be able to do.

Separate lookup from learning

Vonage decided to organise their content according to the Diátaxis framework. This is a framework that we often use (see: Guide and resources for implementing the Diátaxis framework)

The Diátaxis framework divides technical content into tutorials, how-to guides, reference material, and explanation. Each type supports a different need.

That distinction becomes particularly useful when documentation and learning share a site.

• Someone consulting an API reference does not want to be forced through a course. They need an answer.
• Someone learning how to design a video application needs more than a list of endpoints. They need concepts, an ordered sequence, and an opportunity to practise.

Keep those experiences distinct, but connect them.

The documentation should remain the maintained source of technical truth. The learning layer can select and sequence parts of it around a goal. This way, teams can add context, exercises, progress indicators and assessments without creating a second, disconnected, set of product information

This relationship is clear in Vonage’s model.

Its learning centre contains three broad routes:

• Use cases connect a business requirement with a possible technical solution.
• Learning paths take someone through the documentation and exercises needed to build that solution.
• Support paths guide users through situations such as migrating from another product.

The categories are less important than the principle behind them. Organise the experience around user intent, rather than the company’s internal product structure.

Design paths for specific audiences

“Users” can be too broad to be a useful audience definition.

For example:

• A business decision-maker might need to understand what a proposed solution does, why it is worth funding, and which products it involves.
• A developer needs architecture details, implementation instructions, code, and a working environment.
• A support engineer might need a diagnostic sequence.

A good approach is to design connected levels of information. A use-case overview can explain the business problem, expected result and broad technical approach. It can then point developers towards an implementation path. That path can lead into existing explanations, how-to guides, and API reference pages.

Vertical and horizontal use cases can also coexist.

Plan each path by asking:

• Who is this for?
• What do they already know?
• What should they be able to do at the end?
• What evidence would show that they can do it?
• Which existing content supports that outcome?
• What is missing?
• Where are users likely to get stuck?

Certification should follow from the learning design, not drive it. Producing a working result is often the best evidence of learning.

Reuse content without losing context

Learning sites create an obvious maintenance risk. A technical writer updates the documentation, but the course continues to show the old instruction. Users now have two versions of the truth.

Single sourcing reduces that risk.

Vonage manages its documentation through a docs-as-code workflow and uses reusable Markdown content within the learning experience. Docs as code applies software development practices such as version control, reviews, and automated publishing to documentation.

Reusable sections, sometimes called partials, allow the same maintained explanation or instruction to appear in more than one context. The publishing system assembles the appropriate parts into a documentation page, course or learning path.

Reused content needs enough surrounding context to answer:

• Why am I reading this now?
• What should I do with it?
• What comes next?

The safest model separates the source information from the route through it. The facts and instructions are maintained once. The learning path supplies the sequence, purpose, and practice.

Let people build while they learn

Technical learning improves when the user can produce something and see whether it works.

Vonage uses exercises powered by GitHub Codespaces. A codespace gives the learner a configured development environment in the browser. This removes some of the installation and setup work that can prevent an exercise from starting.

The choice of technology will vary. The wider principle is to reduce the distance between reading an instruction and testing it.

An effective exercise should:

• Start from a known environment.
• Ask the learner to make a meaningful change.
• Give a visible result.
• Provide enough diagnostic help to recover from common errors.
• Connect the activity to a real use case.

The exercise should test the capability described by the learning outcome. If the objective is to build an authentication flow, a multiple-choice question about terminology is weak evidence. A working flow is better.

Build the team around the user journey

A documentation and learning service crosses organisational boundaries.

Vonage involved people from API documentation, Developer Relations, UX design, product, product marketing, sales, support, and engineering. That breadth matters because each group sees a different part of the user’s problem.

We’ve seen similar multi-departmental workshops used at other companies, particularly in the communications API space.

Cross-functional workshops can identify the outcomes, audiences, and use cases, before anyone commits to a site structure.

The technical writing team still needs editorial authority. A large group can identify requirements and review accuracy, but content needs named owners, agreed standards, and a controlled publishing process.

Treat implementation as a series of tests

Developing a site like this can take time, particularly if it’s all done in-house. Vonage developed its learning centre through a proof of concept, an alpha, and staged beta releases. Development began in mid-2025, with the public beta opening in July 2026. The team used feedback from internal testers to change both the content and the interface.

That is a more useful model than attempting to migrate an entire documentation estate into a finished learning platform at once.

Choose one important use case. Build the smallest complete path through it. Test whether users can understand the proposition, complete the work, and recover when something goes wrong.

A pilot can answer questions that a specification cannot:

• Are the steps in the right order?
• Does reused content make sense in the learning context?
• Is the exercise environment reliable?
• Can users tell what to do next?
• Where do they abandon the path?
• Which questions still reach the support team?

Expand after the model works.

Measure capability, not page views

Visits and page views tell you that content was opened. They do not tell you whether it helped.

A documentation and learning service needs several types of evidence. Useful measures include:

• Path starts and completion rates.
• Exercise attempts and successful outcomes.
• Where users stop or return to an earlier step.
• Feedback on accuracy and clarity.
• Time taken to reach a defined result.
• Related support demand.
• Product activity following the learning path.

These measures need careful interpretation. A low completion rate might expose a poor course, but it could also mean users found the one answer they needed and left. Analytics should be combined with feedback, usability testing, and support data.

A reporting dashboard is useful only when the team has agreed what decisions the figures will support.

Plan the service before you plan the site

A combined documentation and learning site is not primarily a web development project. It is a content, learning, and governance project, with a web interface.

Start with the users and the outcomes they need. Separate reference from guided learning. Connect use cases to maintained documentation. Add practice where capability matters. Test a small number of paths and measure whether people can achieve the promised result.

Only then decide how the CMS, docs-as-code pipeline, reusable content and interactive environment should support that model.

A large documentation library gives users somewhere to search. A planned learning service gives them somewhere to start, a reason to continue, and a clear idea of what they can do next.

Need help with your developer portal and learning centre?

Cherryleaf can help. See: API and developer documentation that gets integrations working faster