Clean and modern documentation is the standard for developer-first products. The spectrum of provided information goes from a simple API Reference document, like the kind generated by an OpenAPI spec file, all the way to a sprawling knowledge base spanning multiple products, platforms, and languages.
Until now, Shovels was on the simpler end of the spectrum. Don’t get us wrong, this served us and our developer-minded customers very well, but we all knew it was time.
But with the release of docs.shovels.ai, we’re moving closer and closer to the end of the story, and it will continue to grow in tandem with the rest of the Shovels platform.
A Centralized Source for Technical Information
Developers famously prefer to streamline and simplify the learning process as much as possible. They have a mission (understand and use a product) and want to do so as quickly as possible (avoiding lengthy product trial rounds, in-depth sales calls, etc).
A documentation hub is therefore the self-service, one-stop-shop technical resource for anyone, no matter their skill level or familiarity with the product. This has been the underlying methodology for designing our docs hub, and will continue to guide our development of quickstart guides, how-to tutorials, reference, and explanation content (shout out to the Divio method).
So what do those technical resources look like?
docs.shovels.ai stands on the three pillars of Documentation, API Reference, and Release Notes.
Documentation is the largest pillar, which will contain four main components. They are:
- Quickstart Guides: Introductory guides aimed at beginners just starting with the platform. Eventually, we’ll have some in place for each of our three product offerings.
- Tutorials: These are step-by-step walkthroughs of specific actions you can do within the Shovels Platform, and cut right to the chase. The volume here will grow substantially, but we have a few simple ones to get the ball rolling already.
- Troubleshooting: These include FAQs and other commonly cited issues, so that when you run into a problem you can reassure yourself that you didn’t do anything wrong. And as a bonus, hopefully you’ll be able to solve the issue yourself, using our FAQ answers and Troubleshooting guides as a resource.
- Foundations: These are the big-hitting, high-level questions that we often get, but don’t have a simple answer for. Things like “How does Shovels even work?” or “How does Shovels decide which permits to include?” or even “When will you have my permit jurisdiction in your system?” will be answered here.
The API Reference is much more straightforward, and barely has anything added beyond the OpenAPI spec file itself. However, there are a few things of note:
- API Playground: Try out the endpoints in a live playground without the need to build a script externally. Plug in your API key and away you go!
- Request Examples: We provide example requests in a variety of languages to help you build your queries or scripts. If there’s a language you need that isn’t included today, please let us know and we’ll add it.
- Request and Response Schemas: We clearly define exactly what can go into a response, and what we’ll return. This will make it easy to determine which endpoint to use, and which data to extract from the response.
The Release Notes are not technically new, but this is the first time we’re officially hosting them statically, for constant and future reference.
Historically, these went out in a monthly technical newsletter to the active and power-users of the platform, which contained a list of changes made to the schema, field or parameter names, etc.
The new system expands upon this, with the following (broken down by product where applicable):
- New items
- Upgrades
- Breaking Changes
- Bugfixes
- End of Life warnings
- Platform-wide schema changes
These will be updated at minimum once a month with our general release, but if we do any mid-month patches then we’ll include those details as well.
What’s Staying on the Blog?
In the before times, the handy dandy Shovels Blog was where all of this information was sourced. As we expand our platform, individual components will specialize and narrow.
Blog posts about company news, partnerships, customer spotlights, and interesting data analyses will stay on the blog for the foreseeable future.
However, tutorials (like the Shovels 101 series we began last year) will transition into content in our docs hub.
And as always, when there’s something that we write, on either platform (blog or docs hub), that we’re really excited about, you’ll find it on our LinkedIn.
Next-Gen Shovels Support
We’re scaling things up across the board, and that means shoring up our Support. More and more of you are joining and indicating interest in our platform, which means we need to leverage as much self-service help as we can.
This is the best problem to have, so it’s something we’re excited about tackling.
However, we can only make our best guesses (informed by our entire backlog of support tickets and customer conversations, so we’re usually close to the mark) as to what kind of resources and support you will need.
This is an open call from us to you: what do you want to see in a documentation hub? What information do you expect, and to what degree? Help us help you, and you’ll have our long-lasting gratitude. We couldn’t be here without you, and we appreciate every little thing along the way.
Check It Out Today!
If you haven’t already, please give our docs hub a visit at docs.shovels.ai. It will always be a work in progress, but we’re happy with the foundation we’ve built thus far, and it will only continue to grow from here.
Happy Digging (or rather, reading)!