From docs to devs: the new Azion documentation experience
In the vast landscape of software development, crafting a web application can pose challenges, particularly for those starting in the realm of edge computing.
Azion acknowledges a well-rounded documentation portal’s critical role for developers and offers support through our docs portal.
Our focus on creating developer-centric content has led us to revamp our documentation portal to introduce better Azion products for those interested in uncovering the power of edge computing.
The key role of our Product Content team at Azion is to make clear and reliable docs to educate and update our users. By doing that, we amplify the adoption of Azion products, elevate customer retention, and heighten engagement with Azion users and the developer community.
It starts with a ship: tailoring the documentation portal for a developer audience
At the heart of our documentation approach is the understanding that developers are fueled by agility and efficiency, constantly striving for a rapid and seamless workflow. Guided by this insight, our primary objective while architecting each new page on the documentation portal is to ensure that using Azion products becomes a swift and frictionless process.
Our goal as technical writers is to make complex subjects simple and create content that everyone can grasp.
We started by looking at how we organized our portal. Although our content was reliable, the distribution of information, especially to new users, was a proven issue.
- We had one onboarding article that guided the user through creating an edge application but did not introduce how that would benefit them.
- There was also little content about how Azion products work and at which levels.
- The product menu had several shortcomings. Aside from being non-descriptive, it included only main pages, leaving substantial content in what we called “ghost links”, essentially links buried within other paths.
- It also made the products seem much smaller than they actually are by not showing the entire possibilities within the Azion Platform.
Another issue was the gathering of unrelated content under the same umbrella. Terms and conditions, pages about services, the changelog, and a link to the API all shared the same space in the side menu, not separated by category.
Even our own publication process was not without its challenges. When we required something a little more complex, there were several hoops we had to jump through due to our previous architecture. Anything beyond standard Markdown limits was tough to manage.
For instance, implementing a feature that lets developers copy code from a code block, a time saver for any developer, was not something we, tech writers, could do on our own.
Unfurl the sails: migrating documentation to Astro
We realized that if we had to produce content for developers, we would need the best tool for the job. So, starting the journey from the ground up, we first migrated our documentation portal to Astro, a Javascript framework specifically crafted for content-rich websites.
Switching to Astro wasn’t merely a technical change — it marked the start of a refined user experience to improve navigation and usability.
Astro supports componentization, making it easier to create and tailor content according to our needs. It also automatically creates anchor links and a table of contents from high-level headings for easy navigation.
We’ve also capitalized upon MDX, a powerful extension to the traditional Markdown. MDX fuses the convenience of Markdown with the interactive capabilities of JavaScript.
By adopting MDX, we’ve added an extra layer of functionality, enabling us to inject live, dynamic components right into the documentation. The framework even supports dark mode stylization, which many users prefer.
Look to the stars: leveraging the Diátaxis framework
The Diátaxis is a structural model for software documentation. As described by Daniele Procida, it segments the different types of information into tutorials, how-to guides, explanation, and reference.
Tutorials and explanations cater to the learning-oriented needs of users, while reference and how-to guides are task-oriented, helping users achieve goals for work purposes. Both types can cover basic or complex tasks, with the distinction lying in whether the user needs to acquire knowledge or apply that knowledge.
Our priority so far has been to focus on robust and precise reference documentation while we rely on how-to guides and developer-focused resources for support.
There was a clear separation in the navigation bar between the Documentation home, where you’d find references to our products and features, the Guides page, which housed a list of guides, and the Dev Tools home, where users could learn more about the CLI, SDK, and other tools and integrations targeted towards developers.
We saw the potential for expanding how-to guides and explanation into our home page, effectively drawing new users into edge computing. Thus our first challenge was set: we would blur some lines we drew between our documentation.
Navigate the edge: a quick onboarding to edge computing
We began by defining what type of content should earn the most privileged position at the top of the side menu. The prime idea was to add more insight into the world of edge computing and its significance in the current tech landscape. We played around with a timeline and expansive articles spanning the benefits of edge computing, but we landed on something more straightforward.
With the section titled Before you begin, we launched two new articles: Core concepts and Get help. The first article familiarizes new users with the Azion Edge Platform and its edge computing abilities. The following article highlights resources for users seeking further information on the subject.
Full speed: launching an edge application with a few clicks
The second priority we had with our documentation portal was highlighting how quickly users can build an edge application with Azion. Hence, we added the Get Started section in the left menu.
Instead of building an application from scratch, we’ve tailored an introduction for our new users on the Welcome to the edge page. This page is the starting point, offering an overview of Azion’s products.
From there, users can transition into the Start with a template page. This page focuses on how users can leverage our templates to streamline the process of building edge applications.
Once the edge application is set up, the next step is to launch. Go live with Azion incorporates quick guides outlining the options available for launching edge applications.
Lastly, the View metrics article is invaluable once the application goes live. It goes beyond the basic setup and allows users to delve deeper into their application’s performance by monitoring and analyzing access and activity data.
Enjoy the journey: building at the edge
To follow up the template-driven approach for application development on Azion, we decided to let the user choose which step to take next once their application was live: calling it the Choose your journey section.
Each journey takes the user to another home page with a brand new left menu. Each home focuses on a different set of Azion products.
- Build allows developers to build APIs or web applications to run on Azion’s edge network.
- Secure provides a fully-featured Zero Trust Security model that is simple to adopt and scale up.
- Deploy leverages Azion’s highly distributed network, multi-cloud, or on-premises.
- Observe enables users to monitor and access data.
Starting with the Build journey allowed us to experiment with different content configurations and formats while establishing a clear blueprint for the remaining journeys.
While the home page drew attention to the template-driven approach for launching an application, Build turned to all of Azion’s possibilities when developing an edge application.
Commencing with an Overview page, we’ve sought to offer users a bird’s eye view of the Edge Application product, equipping them with an understanding of how it works. Following that, the Build an Application segment introduces the spectrum of tools available for application configuration and quickly guides users through the customization process, unveiling its major steps.
When users explore Edit an Application, they come into contact with our how-to guides focused on how they can customize each aspect of their application, such as caching at the edge or implementing edge functions.
We explain how these configurations can be executed through various tools available on the Azion Platform. This includes the Real-Time Manager — a system designed for live monitoring and configuration — and the Azion API — an essential component for users aiming to create a more integrated and automated workflow.
Another goal of this journey was to introduce the steps, codes, libraries, and functions available to developers to help them complete their projects. Through the Develop with Azion section, we listed all the tools and integrations available to developers.
We also sought to integrate other methods to work with applications beyond the coding level with environment variables. The final section ties into ways users can ensure application observability through Understand metrics and Debug applications.
Drop the anchor: incorporating development into guides
With this intent in mind, we introduced API usage to guides. Instead of only focusing on steps via the Real-Time Manager, a significant update was the addition of instructions to run the API through cURL commands.
This ensures that our users receive a complete how-to guide that is not just limited to one method. This way, we cover our basis and enable users to opt for an approach that best aligns with their workflow.
But that doesn’t mean we swept the conventional reference pages under the carpet. These pages remain significant in our documentation utility belt, available for quick reference and traditional lookup.
Looking ahead to what the future has in store, we plan to introduce various new tools and features designed for developers to streamline their processes.
As these tools and functionalities are launched, our mission is to consistently update our guides and provide clear usage instructions through applicable examples. This includes the upcoming Azion CLI commands for Edge Application and other integrations such as Templates.
We want to ensure that developers have the most up-to-date, valuable, and actionable resources at their disposal to fully grasp the power of the Azion Edge Platform.
No man is an island: opening the Azion Docs repository for contributions
Making software documentation on Github public fosters transparency and gives voice to the Azion community. By allowing open contributions to the Azion Docs Github repository, we tap into the collective intelligence of developers, further refining the accuracy of the documentation and keeping it up to date.
Throughout our journey to making our repository public, we’ve underscored the importance of the README file. This crucial component serves not just as a welcoming note but as a clear and concise guide that effectively introduces newcomers to the portal and meticulously explains repository usage.
Further driving consistency and contributing to the collaborative environment we aim to promote, we have implemented standardized templates for issues and pull requests. These templates are pivotal in shaping contributions to be more structured and legible.
Moreover, this strategy ensures that all contributions adhere to a set of conventions, simplifying the process of reading repository history. These standardized conventions facilitate the communication between the technical writer team and contributors, driving us to a more efficient workflow.
We invite everyone to share their feedback through Github, whether big or small. Contributions can pave the way to making our documentation portal even better.
Final thoughts
By shifting our focus to instructional content, we enhance the learning experience of developers by fostering understanding and hands-on experiences with Azion products.
So jump aboard to build, secure, deploy, and observe your applications with Azion in this exciting innovation journey on edge computing.
You can learn more about Azion — and our tech writing team of course :D — to kickstart your development journey at the edge for free: enjoy our $300 in credits to start building your applications.
Grab a coffee!
We're waiting for you in our dev community :)
