// Here there! My name is Daan and I'm one of the co-founders at Alphadoc. Follow me on LinkedIn where I post more (hopefully) helpful things.

Enhance API Learning with Alphadoc's Diagrams & Tutorials

The end of the year is coming up and we'd like to take some time and review what we deployed this year and also take the opportunity to dive a little bit deeper into some of the main features we released this year. This series of posts is showcasing some of the feature highlights of the past year we are particularly proud of.

Why do diagrams and tutorials matter

Diagrams have always been excellent communicators of processes where there are many different moving parts. The best example I can give is to try putting together an Ikea closet with instructions that are 100% text, you would lose your mind. 

I admit, API integrations are way more complex than Ikea closets. Diagrams help you tell a story and make it easy to zoom out to get a full picture.

These are some tips on creating diagrams that actually help you explain your API. Start by describing what the integration looks like. Use these questions to help you find the answers:

• What data do I need for an API call and where is it coming from?

• Which endpoints/SDKs can I use?

• Are there humans that need to provide input or approvals?

• Is my use case already described?

These questions will come up during the process of learning about new APIs.

The writers challenge

If you are the one that is writing the content, your challenge is to write something for *someone* on the internet without speaking to them. 

• You don't know what language or framework they are working in

• How technically adept they are

• Why they are reading your content

Most of the time you don't know if your content helped them. If you see in your analytics tools they stayed on a page for a long time, does it mean the page helped them, or it took a long time to read? 

Developer docs sometimes have a rating system with a "Was it helpful: Y/N" - which is commonly known as giving insights only once you start to hit scale with your content. Are you hitting scale yet? If not, you have to rely more on some ground rules to get ahead.

“On top of all of these unknowns regarding your audience, you'll need to be able to quickly add new content for the latest and greatest features your team is pushing, and update all the existing content as well.”

Progressive Disclosure (PD) and Singular Adaptability (SA)

Okay... so what did we make to help out? After our research and validation phase, we came up with two principles that help us build features to make developer and API documentation better. We call them "Progressive disclosure" and "Singular Adaptability".

Progressive Disclosure (PD) is about revealing information progressively as the user needs it, reducing information overload and cognitive strain. Interactive API diagrams are a good example. A diagram will provide a high level overview and as you navigate through the diagram you should be able to learn how to perform the API calls described in the diagram. That's how we did it.

In other words: This is like learning to build a house step by step. You start with the basics, like designing a blueprint, and gradually move to more complex tasks, like electrical wiring, as you become more skilled.

Singular Adaptability (SA) refers to Alphadoc's capability to be effectively used by a wide spectrum of users, from novices to experts, without the need for repetitive explanations or instructions by the writers. To facilitate this, Alphadoc starts from the writer's point of view.

When you make a new guide, tutorial or other piece of content about an integration, ideally - your whole audience can consume it. Let's assume one part of your audience is novice coders and they are not familiar with your API. The other part of your audience is experienced developers that know your API.

You have to find balance - do you adapt the context and make the content suitable for the novices or do you keep it lean for the experienced developers? Alphadoc's singular adaptability shines here. The combination of endpoints and diagrams allows for both detailed and high-level views, catering to the diverse needs of your audience without repeating content.

In other words: It's like having a construction manual that changes based on who's reading it. A novice might see basic building instructions, while an expert gets detailed architectural strategies, all from the same manual.

How we apply PD and SA

We now know about the challenges that writers and readers endure, and principles that we are applying to solve them. In the previous part of this series I spoke about our API endpoint - which has the Progressive Disclosure (PD) and Singular Adaptability (SA) built in its core, with code examples, links taking you to more detailed pages and more!

Demo video of Job explaining the feature:

Implementing PD and SA

1. Layered Information: Alphadoc presents information in layers. Beginners might see the basic overview, while advanced users can dive into the deeper, more technical aspects. 

2. Interactive Elements: Users can interact with diagrams and tutorials, choosing what information they need to see based on their proficiency level. 

3. Customizable Views: Alphadoc offers customizable views of documentation, allowing users to tailor the information displayed to their skill level and needs. 

4. Contextual Help: For novice users, additional context is provided as needed, while ensuring that this doesn’t clutter the experience for more advanced users. 

5. Real-time Updates: As your API evolves, Alphadoc updates all related documentation in real time, ensuring consistency across all levels of detail.

How do diagrams and tutorials work?

A tutorial is a group of endpoints that you have added in a step-by-step interface and can optionally add 2 or more endpoints together to carry over the response data of API call 1 with the request data of API call 2. After you have connected a few API calls you can switch to the diagram view and you'll see the diagram that represents the flow. By using our customizable endpoints in a chain of steps we are ticking the boxes of PD and SD! On top of that we do a few nifty things like type checks to make sure you're not assigning invalid strings to integer fields and you can see when a diagram won't work anymore.

Low maintenance and auto updating

Any changes are immediately reflected in the API diagram and making edits is quick. As a bonus, the API diagrams are now source controlled from your OpenAPI specification. If you upload a new spec file with new items like parameters or updated descriptions, both the tutorial and the API diagram will automatically update.

Summary

With tutorials and diagrams - we introduce a completely new way of making interactive content. The diagram generating tutorials are a great way to build content that a variety of different technical backgrounds (Singular Adaptability) will find easy to consume - and we make it much easier to learn new concepts by applying principles of Progressive Disclosure.

Sign up for an account at https://docs.alphadoc.io/sign-up