We are excited to announce that we’ve completely refreshed our docs site! Taking into consideration both user feedback and industry best practices, we’ve redesigned the site to provide users with a more intuitive experience and rewrote our docs to ensure that it is clear and concise.

Approach

One of the biggest changes we made is the complete restructuring of the docs site. We simplified the navigation, making it easier for users to find the information they need. The Diataxis Framework served as inspiration with its four distinct categories—Tutorials, How-to Guides, References, and Explanations—that serve to provide clarity to both the author and the reader. Using this framework as a guide, we implemented our own new categories:

• Getting Started: Tutorial-style documentation to help new users learn how to get started on Aptible (e.g., Starter Guides)
• Core Concepts: Explanation-style documentation of how Aptible works and how to use it (e.g., an Explanation of what a Stack is)
• Reference: Reference-style documentation with information to refer to as you use Aptible (e.g., CLI commands)
• How-to Guides: How-to-guide-style documentation with a series of steps to complete a goal (e.g., How to upgrade a Database with Logical Replication)
• Troubleshooting Guides: How-to-guide-style documentation with a series of steps to resolve common issues and errors users experience on Aptible (e.g., Build Failed Error)

Content Improvements

Based on feedback from our new and existing users, we have rewritten most of our docs to improve overall clarity. We recognized that some of our docs covered advanced DevOps topics, which led engineers to search for additional resources. With the rewritten docs, we aim to address this issue by providing comprehensive explanations that don't require users to seek external information. Our goal is to equip our users with all the knowledge they need within our docs itself.

In addition, we have improved Starter Guides to align with our new Deploy Code from the Dashboard release. This exciting feature allows users to deploy a Starter Template directly from the Aptible Dashboard, simplifying the deployment process. The updated Starter Guides will guide users through the new workflow step-by-step, ensuring a smooth onboarding experience.

Improved Search

To enhance the search experience, we implemented an improved search functionality that includes preview text. Users can now get a glimpse of the content before diving into the full document, making it easier to find the information they’re looking for.

Visual Improvements

We restyled our doc site last month, but to further enhance the visual experience, we have added over 40 reference images throughout our docs. These visuals aim to clarify concepts, illustrate workflows, and give users visual cues to navigate the Aptible Dashboard.

Widgets

But that's not all! We have also introduced new widgets to our docs site, making it even more convenient for users to engage with our platform. You can now easily submit tickets from docs and access our roadmap and submit ideas within the docs itself. Additionally, we've connected our status page to our docs site so that in the event of an outage, a notification will display directly in our docs.

Conclusion

We are thrilled to present these updates to our docs site, and we believe that they will greatly improve your experience as you explore our platform. Our commitment to providing clear, concise, and user-friendly docs remains unwavering. We hope that these changes will empower you to make the most of our services without any hurdles.

If you haven’t seen it - take a look! We welcome all your feedback on our new doc site. If you have any suggestions or ideas for further improvement, let us know!

Happy deploying!