Introducing the New SurrealDB Documentation on Docusaurus!

by Obinna Ekwuno, 4 min read

We are excited to announce the new SurrealDB documentation - /docs/.

At SurrealDB, we are constantly looking for ways to improve the experience of developers on our platform, which has led us to rethink our documentation platform.

We decided to transition to Docusaurus for a variety of reasons. First and foremost, Docusaurus provides a simple, user-friendly platform for building and maintaining project websites. This is particularly valuable for us, as it allows us to focus on creating quality content rather than dealing with the complexities of website development.

Moreover, Docusaurus supports Markdown and MDX, enabling us to write in a familiar and easy-to-use format. Lastly, it is easily customisable, which allows us to build-in search functionality powered by SurrealDB.

We have also added the following features:

Added Search functionality: We’ve added a new search system that allows users to quickly find the information they’re looking for, powered by SurrealDB Full-text search.
Improved Content Discovery: We’ve arranged our content into specific topics to help users find relevant information more easily by improving linking and discoverability.
User-Friendly Layout: We’ve redesigned our documentation to make navigating and finding the information you need easier.
Versioning Support: We’ve integrated versioning, allowing users to easily switch between different versions of the software and find the information relevant to their needs.
Mobile-Friendly Interface: Our new documentation platform is fully responsive and optimised for mobile devices, ensuring you can access our documentation anytime, anywhere.
Improved Accessibility: We’ve made efforts to ensure our documentation is accessible to all users, including those with disabilities, providing alternative text for images and ensuring our site is navigable using keyboard commands.

Our transition to Docusaurus was not a decision made lightly. It’s a crucial step towards providing documentation that is as efficient, user-friendly, and comprehensive as possible.

Added search functionality

At SurrealDB world, we launched SurrealIX, which included our suite of search and indexing products.

Building on this, we’ve integrated SurrealIX into our documentation, powering a robust, full-text search system that enables users to locate the information they need easily and quickly.

This new search functionality not only improves the user experience but also showcases the capabilities of our own SurrealIX product.

Improved content discovery

Over time, we received a lot of feedback from the community about the difficulties in finding specific information in our documentation. We have taken this feedback to heart and have made significant improvements to our content organisation. We aim to make finding relevant information as smooth and intuitive as possible.

We have done this by enabling direct linking between sections of documentation and also making that discoverable via search.

The sidebar has also been updated to aid content discoverability. We have made the SurrealQL statement section alphabetical to allow you to find information intuitively.

In addition to improving the structure, we have added a new ‘How-to’ section - /docs/tutorials/integrate-auth0-as-authentication-provider

Accessibility

We’ve taken numerous steps to ensure our documentation is accessible to everyone, including those with disabilities. We’ve integrated keyboard navigation commands on our site, implemented high-contrast themes for better readability, and included alt text for all images to improve accessibility for visually impaired users.

We have also improved our code blocks so that code can now be copied using our SurrealQL grammar, so you can now use SurrealQL as a language across docs.

Localisation

Currently, we only support English. However, we plan to introduce more language support in the upcoming months and open this up for community contributions. This will make our documentation more accessible to a broader range of users across the globe.

Please feel free to reach out to us via our community channels with suggestions on language support.

Future plans

We are committed to continuously improving our documentation and providing the best possible experience for our users. As part of this commitment, we have several exciting updates planned for the future.

Community Contributions

We believe in the power of community and the value that individual contributions can bring. We are currently working on a system to allow users to contribute to the documentation, making it a collaborative effort that benefits all users.

Interactive examples

We understand that learning is often best done through hands-on experience. To this end, we plan to introduce interactive examples in our documentation, allowing users to learn by doing.

Expanded Content

While our current documentation covers a comprehensive range of topics, we are always looking to expand. We plan to introduce new sections and topics based on user feedback and emerging trends in the industry.

Localizations

We appreciate that our user base is global and want our documentation to reflect this diversity. We plan to offer our documentation in multiple languages to cater to non-English speaking users.

We look forward to implementing these updates shortly and continuing to serve our user community with top-notch documentation.

Conclusion

The new SurrealDB documentation represents a significant step forward in our commitment to providing high-quality, user-friendly documentation that meets the needs of our users. The move to Docusaurus will significantly enhance the user experience, making it easier for users to find the information they need and navigate our documentation.

We’re excited about the new features and improvements that this transition brings, and we’re looking forward to continuing to improve and expand our documentation.

We appreciate the feedback and support from our users and community and are committed to continuing to serve you to the best of our ability. Please join our community to share your experience and check out the Documentation GitHub repository.