AVEQ Opens Up: Surfmeter Documentation Now Public
We’re happy to announce that we’ve taken a significant step forward in our transparency and ease-of-use by opening up our Surfmeter documentation to the public. We want to provide comprehensive, accessible information about our video streaming (and network performance) monitoring solutions, and you should be able to read it without signing a non-disclosure agreement or going through multiple sales calls. Read on to find out more.
Why Open Up Our Documentation?
At AVEQ, we believe that great technology deserves great documentation. A piece of software is only useful when it can be used properly. Previously, our docs were available only to interested parties after them entering the typical B2B sales cycle with one or more calls, and us sending a demo version of the software, along with the docs.
But these days, software buying decisions are no longer made like that — or at least not in all cases. At AVEQ we love to speak with technical folks directly. Our ideal customer is one who also enjoys going into the nitty-gritty details like we do, as programmers/IT people. But they also need purchasing power, or at least have to weigh into the buying decision.
It’s hard to know whether a tool supports your use case unless you can see its capabilities. And short of actually running it yourself, the documentation is the next-best alternative. Because let’s face it: the average marketing-oriented landing page doesn’t cut it when you need to know exactly how the product works from a technical perspective.
So, by opening up our documentation, we’re:
- Making it easier for possible buyers and (later) users to find answers to their questions — no need to talk with anyone or sign a contract beforehand
- Demonstrating our commitment to transparency and openness — because many vendors don’t share even the slightest information about their tools, and we want to do better
- Providing a more seamless experience for developers integrating with our solutions — no going back and forth, making it easier for us (less direct support) and them (e.g., in the case of time zone differences).
What’s Included in the Documentation?
Our comprehensive documentation covers all aspects of the Surfmeter ecosystem:
Surfmeter Automator: Our flagship automated platform for measuring the performance and quality of OTT video streams like Netflix and YouTube. The documentation includes detailed guides on installation requirements and setup (including Docker options), basic usage and commands, running studies and changing configurations, and advanced features like screen recording and network request logging.
Surfmeter Mobile Quality SDK: For developers integrating mobile video quality and network performance measurements into their applications, we provide installation instructions and basic usage guides.
Surfmeter Player SDK: Available for Android, iOS, and Web platforms, with platform-specific documentation covering installation procedures and usage guidelines.
Technical Reference: For those who need deeper technical details, we provide reference documentation on the available studies (i.e., the types of measurements we do), the configuration options, measurement data specifications, and — very important — the KPIs that we measure, i.e., the statistic values and client reports.
Here, we additionally provide details about the video QoE model, like how to analyze our QoE model reports. The QoE model is at the core of our technology, and there are different operational modes and versions of it, so it’s important to describe its inner workings.
Built with Modern Documentation Tools
Our documentation is built using MkDocs — with the exceptional Material for MkDocs theme, providing a beautiful, responsive, and feature-rich documentation experience. Some highlights of our documentation system include:
- Responsive Design: Documentation that looks great on any device
- Dark/Light Mode: Support for both light and dark color schemes (because nobody can agree on what’s the best mode)
- Advanced Search: Full-text search with highlighting and suggestions
- Code Highlighting: Clear syntax highlighting for code examples, with platform-specific advice and inline annotations
- Interactive Features: Tabbed content, copy buttons for code blocks, and more
- Automatic Schema Tables: Generated from our JSON Schema definitions
Material for MkDocs allows us to create a documentation site that’s not just informative, but also a pleasure to use — as a user and as a developer. Pushing changes to the docs should be as simple as editing a text file and running a small script. We (as developers) don’t want to fiddle around with the WordPress GUI. MkDocs makes this a breeze.
Schema-Driven Documentation
One of the unique aspects of our documentation is the automatic generation of reference tables from JSON Schema definitions. Essentially, we provide our internal documentation directly in the source code, as comments in the TypeScript codebase. From this, we can automatically generate JSON Schema for various data structures. The JSON Schema is the ground truth for the rendered tables in our docs. This ensures that our documentation always stays in sync with our actual implementations, providing accurate and up-to-date information for developers and users.
Getting Started with Our Documentation
The documentation is now available at https://docs.aveq.info/surfmeter-docs/ — we hope you enjoy browsing it!
