In this update, rather than focus on new features of Hive, we’ll be highlighting some of our thoughts and reasoning for as well as strategies applied in the recent changes to the Hive documentation.
It feels a bit silly to be posting an update about documentation, but it’s important as open source developers to treat documentation as an extension of our code. Documentation gives a place to explain things in far more detail or to a specific audience. It would be impossible to convey such detail through the user interface or API alone.
So what motivated us to take a closer look at our documentation?
A fundamental shift in how we think about Hive
Hive started as “only” a schema registry. We weren’t sure what direction this would go in the future, but thought features would keep being added to the core product. We also knew people needed to be able to self-host Hive. So this lead to a common industry distinction of “cloud” vs “self-hosting” offerings.
At the time, this made sense. GraphQL Federation was still young and GraphQL routers in their infancy. But Federation was growing and the need for a powerful and customizable router was clear. We knew it needed to work well with our schema registry also, and to make that point clear to others, this router was called Hive Gateway. More recently, our offerings have expanded to include a Hive Logger, built with our logging needs and best practices in mind, and soon a new Hive Router, written in Rust.
Hive is growing…
Our suite is growing and it’s become confusing to talk about “Hive” as a cloud service, since these products span different spaces. What was once called “Hive” is now a part of the whole. The schema registry has expanded as expected, but so has the brand. And so we needed to adapt.
This has been a very organic process for us. Which honestly is great because we can find gaps in the GraphQL ecosystem, work on solutions, and let our work inform our brand. We can be sure that we’re building solutions to real problems because of this, but our documentation had some growing pains as a result.
Input from the community
Feedback and questions from the community have made the shortcomings of our documentation even more clear. There was often confusion around cloud hosting our Gateway (which we don’t offer, at least at this time). Additionally, our API Reference documentation was scattered and we’d often get questions about how to do certain custom tasks.
Rather than get annoyed any time a question is asked more than once, it’s best to take a look at the cause. 99% of the time it’s because the documentation is missing, hard to find, or generally unclear.
Industry changes
GraphQL has been changing this whole time as well. As mentioned before, Federation was new when Hive was first built. People are much more familiar with the concepts of Federation now and it’s been gradually shifting from a single company’s offering (Apollo Federation) to an open spec (GraphQL Federation). So terminology needs updated.
What we did
Let the products speak
We updated the introduction/landing page to instantly showcase our product offerings. This makes it clear that these are modular, pieces of the whole, and gives us a fantastic place to briefly introduce each. Additionally, since Hive Console was the only product in the past, there were a lot of documents that were specific to Hive Console that were still at the root of the Hive documentation. This was solved by creating separate pages for each product and moving these pages inside.
Collapse when possible
Previously there were separate root level pages for CLI/API References, Specifications, and our public GraphQL API. This was because we thought each had a separate audience and were conceptually different, but what we’ve discovered is that if people are looking at reference documentation, then they likely care about all of this. The audience for all of these sections included “power users”, who wanted to write custom tools or interfaces for Hive. So we collapsed all of this to a single location, making it easier for power users to browse for what they need. — And this is just one instance. There were (and probably still are) numerous parts of our documentation that were redundant.
Conclusion
Much like our code bases, documentation ages. Not only because of UI or API changes, but because the entire product or the world around it might change. Staying organized helps since pages are more searchable, but documentation is often too easy to forget to update.
Hopefully you’ve found this post interesting and learned a little more about Hive in the process. I have no doubt that our documentation will continue to evolve alongside Hive moving forward. And if you see something that doesn’t make sense, don’t hesitate to ask. There’s no such thing as a stupid question — there’s only neglected documentation.